Windows Media Player 7.1 SDK

This documentation describes the Microsoft® Windows Media™ Player 7.1 Software Development Kit (SDK). The Windows Media Player SDK is one of the main components of the Microsoft Windows Media SDK. Other components include the Microsoft Windows Media Format SDK, the Microsoft Windows Media Services SDK, the Microsoft Windows Media Encoder SDK, the Microsoft Windows Media Rights Manager SDK, and the Microsoft Windows Media Player SDK.

The Windows Media Player 7.1 SDK documents programming technologies that can be used to extend the capabilities of Windows Media Player. These technologies are documented in the following sections:

Section | Description
Windows Media Player Object Model | The Microsoft Windows Media Player control is a Microsoft ActiveX® control used for adding multimedia playback capabilities to Web pages. It provides a programming interface for rendering a variety of network streaming and non-streaming multimedia formats. This portion of the SDK also contains information about the Windows Media Player 6.4 Object Model, Windows Media Player Netscape Navigator plug-in 6.4, Windows Media Player for Mac, and Windows Media Player plug-in for Solaris 6.3.
Windows Media Player Skins | Skins are an XML-based technology used to customize the user interface of the stand-alone Windows Media Player.
Windows Media Player for Palm-size PC, Pocket PC, and Handheld PC Skin Development Kit | Skins are an XML-based technology used to customize the user interface of the Windows Media Player. This section discusses creating skins with Windows Media Player for Palm-size PC, Pocket PC, and Handheld PC.
Windows Media Player Custom Visualizations | Windows Media Player visualizations are COM objects used to display visual imagery that is synchronized to the audio portion of the media playback of the player. Custom visualizations can be created using Visual C++.
Windows Media Metafiles | Metafiles are XML documents that provide information about a media stream and its presentation. Metafiles can be used to organize media files into playlists that can include functionality for seamless stream switching, ad insertion, and other features.
Glossary | This section contains definitions of terms used throughout the SDK.

Notes Installing this SDK does not install Windows Media Player. You must have Windows Media Player 7.1 installed to use the material in this SDK.

Samples for this SDK are in the Samples folder that is installed with the SDK. The file named Wmp7sdkr.htm has a list of the samples. You must first install the Windows Media Player SDK to use the samples. If you have not already installed it, click the following link:

Install Windows Media Player SDK

Next

© 2000-2001 Microsoft Corporation. All rights reserved.


Windows Media Player Object Model

The Microsoft® Windows Media™ Player ActiveX® control object model provides scripting interfaces to give Web developers the opportunity to add Windows Media Player functionality to Web pages. By embedding the control in an HTML page, the developer can use Internet Explorer to craft visually complex graphical environments that take advantage of a rich and dynamic event model. The developer can completely sculpt the Web-site user's audio and video experience.

If you have worked with previous versions of the Windows Media Player ActiveX control, please read the topic called What's New, because this version has many changes that are significant.

The Windows Media Player ActiveX control object model documentation is presented in the following sections.

Section | Description
About the Player Object Model | Discusses the architecture of the version 7 or later object model in abstract terms. You can read this section if you want to know more about how things work "under the hood."
Player Control Guide | Explains what you need to do to program using the version 7 or later control object model. Read this section unless you are already familiar with using ActiveX controls on a Web page and know how the Windows Media Player control works.
Object Model Reference | Documents every method, property, and event that the version 7 or later object model exposes. Read the topics that refer to the functionality that you want to use.
Windows Media Player Version 6.4 Plug-in for Netscape Navigator | Explains what you need to do to use Windows Media in the Netscape Navigator browser. There is also documentation in this section for Windows Media Player for Solaris and Windows Media Player for Mac.
Previous Version | Documents Windows Media Player version 6.4, which can be embedded in COM-based documents and applications as well as Web pages.

Windows Media Player 7.1 does not support embedding the control in any applications that use Microsoft Visual Basic or Visual C++ through IDispatch. Also, version 7.1 does not support a Netscape Navigator plug-in. For these reasons, both the 6.4 and 7.1 versions of the control are installed when the end-user installs Windows Media Player. The new control and the old control have different ClassID numbers, different object models, and different sets of functionalities.


About the Player Object Model

The Microsoft® Windows Media™ Player control is a standard ActiveX® control that uses Microsoft Component Object Model (COM) technology. The Windows Media Player functionality is distilled into a set of programming interfaces that follows standard COM guidelines. You can program these interfaces on a standard HTML Web page using the player control object model with Microsoft JScript® or Microsoft Visual Basic® Scripting Edition (VBScript). You can also program them in skins using Microsoft Jscript®. Only these two scripting languages are supported in this release.

Using the control with Microsoft Visual C++ or Microsoft Visual Basic or other languages using the IDispatch interface is not supported in this release.


What's New

Three major changes have been made in the Windows Media Player control since version 6.4.

  1. The control has a new CLSID. It is 6BF52A52-394A-11D3-B153-00C04F79FAA6. The old control is still shipped with this version of the Windows Media Player SDK to ensure that previous Web pages function correctly. But if you want to take advantage of the new functionality of the control for this version, you must change your CLSID.
  2. The control has been split into subcontrols, including Controls, Settings, and Network. Methods, properties, and events that are attached to the main control are documented under the Player object. See the Control Reference for more information. Methods and properties of the subcontrols are accessed through the player. For example, to use the bandWidth property of the Network object, you must type:
    player.Network.bandWidth
  3. The following version 6.4 methods and properties are no longer supported in the Windows Media Player control:

    AboutBox

    AllowChangeDisplaySize

    AnimationAtStart

    AudioStream

    AutoRewind

    CanPreview

    CanScan

    CanSeek

    CanSeekToMarkers

    ChannelDescription

    ChannelName

    ChannelName

    ChannelURL

    Codec Count

    ConnectionSpeed

    ContactEmail

    ContactName

    ContactPhone

    CreationDate

    DisplayBackColor

    DisplayForeColor

    EnableFullScreenControls

    EnablePositionControls

    EnableTracker

    ErrorCorrection

    GetCodecDescription

    GetCodecInstalled

    GetCodecURL

    GetMediaInfoString

    GetMediaParameter

    GetMoreInfoURL

    GetStreamGroup

    GetStreamName

    HasMultipleItems

    IsBroadcast

    IsDurationValid

    IsPlaylist

    IsSoundCardEnabled

    Language

    Open

    PlayerMode

    PreviewMode

    ReadyState

    SelectionEnd

    SelectionStart

    SendErrorEvents

    SendKeyboardEvents

    SendMouseClickEvents

    SendMouseMoveEvents

    SendOpenStateChangeEvents

    SendPlayStateChangeEvents

    SendWarningEvents

    Show Dialog

    ShowAudioControls

    ShowCaptioning

    ShowControls

    ShowDisplay

    ShowGotoBar

    ShowPositionControls

    ShowStatusBar

    ShowTracker

    Stream Select

    VideoBorder3D

    VideoBorderColor

    VideoBorderWidth

    Warning


Player Object Model

ActiveX uses the concept of objects to contain programming functionality. Windows Media Player uses several objects to divide up the work that the control does. The root object is the Player object, and the other objects are attached to the Player object through specific properties.

The following diagram shows how the Windows Media Player ActiveX control model works:

Player---------Settings(by Settings property of Player)
       |
       ------Controls(by Controls property of Player)
       |
       ------Network(by Network property of Player)
       |
       ------CDRomCollection (by the CDRomCollection property of Player)
       |     |
       |     ------CDRom(by Item property of CDRomCollection)
       |
       ------PlaylistCollection (by PlaylistCollection property of Player)
       |     |
       |     ------Playlist(by Item property of PlaylistCollection)
       |
       ------MediaCollection(by MediaCollection property of Player)
       |     |
       |     ------Media(by Item attribute of MediaCollection)
       |     |
       |     ------StringCollection(by GetAttributeStringCollection property of MediaCollection)
       |
       ------Error(by Error attribute of Player)
       |     |
       |     ------ErrorItem(by Item property of Error)
       |
       ------ClosedCaption(by ClosedCaption attribute of Player)

Note that it is also possible to access a current object directly. For example, you can get the current media object by using the currentMedia property of Player.

The following properties can be used to access current objects:

  • player.currentMedia access the current media item
  • player.controls.currentItem also accesses the current media item
  • player.currentPlaylist accesses the current playlist


About the Player Object

This is the core object for the Windows Media Player control. All other related objects are connected to this object through specific properties which return the object. For example, the Settings object is accessed through the settings property and uses the syntax player.settings.volume, where player is the ID value you set in the OBJECT tag. The Player object contains methods, properties and events that relate to the core functionality of Windows Media Player.

Because this reference is also to be used for skins programming, the ID of the Player object will be "player" for syntactical examples.

Using the player global attribute within a skin definition file gives access to the Player object for use in scripting. Through the Player object, all other objects in the Windows Media Player control become accessible to scripts as well. The events of the Player object and the URL property can also be specified at design time using the PLAYER skin element. For more information, see Windows Media Player Skins.


About the Settings Object

This object governs the settings of the control such as volume, play count, mute, and so on. It is accessed only through the Settings property of the Player object. The Settings property returns the Settings object. You can only access the properties of the Settings object after you have created it. For example, to get the value of the Volume property, you must use the following code:

     myvolume = player.settings.volume


About the Controls Object

This object governs the transport of the media content through the control, by using methods such as Play and Stop. It is accessed only through the Controls property of the Player object. The Controls property returns the Controls object. You can only access the properties of the Controls object after you have created it. For example, to use the Play method, you must use the following code:

     player.controls.play()


About the Network Object

This object governs the properties that allow you to determine how well the content is streaming through the network. For example, you can find out whether packets are being lost and take appropriate action. The Network object is accessed only through the network property of the Player object. The network property returns the Network object. You can only access the properties of the Network object after you have created it. For example, to use the Bandwidth property, you must use the following code:

     mybandwidth = player.network.bandwidth


About the Cdrom and CdromCollection Objects

These objects govern the interface to the CD-ROM in your computer for purposes of reading and playing.

The CdromCollection object is accessed only through the cdromCollection property of the Player object. The cdromCollection property returns the CdromCollection object. You can only access the properties of the CdromCollection object after you have created it. For example, to use the count property, you must use the following code:

     mycount = player.cdromcollection.count

You can only access the Cdrom object through the CdromCollection object. For example, to eject the CD by using the Eject method, you must first create the collection object and then an item in the object. To eject the CD, use the following code:

     player.cdromcollection.item(0).eject();

In both cases, you are first creating the collection object (CdromCollection) and then getting a specific object of that collection. The object is the first item in the collection, Item(0), which corresponds to the first CD drive. You then call a method, Eject, on that item.


About the Playlist, PlaylistCollection, and PlaylistArray Objects

These objects govern the playlists that Windows Media Player can use to sequence the content being played. You get the PlaylistCollection object from the playlistCollection property of the Player object. The playlistCollection property returns the PlaylistCollection object. You can only access the properties of the PlaylistCollection object after you have created it. For example, to create a new playlist, you must first get the PlaylistCollection object and then use a method on that object.

     player.playlistcollection.newplaylist('myplaylist')

You can get the current playlist by using the currentPlaylist property. For example, to get the name of the current playlist, use the following code:

     myname = player.currentplaylist.name

The PlaylistArray object is returned by the getAll and getByName methods of the PlaylistCollection object. To get the number of playlists, for example, use the following code:

     howmany = player.playlistcollection.getAll().count

To retrieve a known playlist by name, use the following code:

     if (player.playlistcollection.getbyname('myplaylist').count == 1) {
       pl = player.playlistcollection.getbyname('myplaylist').item(0)
     }


About the MediaCollection and Media Objects

This object governs the media collection, which defines the locations of media files that Windows Media Player can access. You get the MediaCollection object from the mediaCollection property of the Player object. The mediaCollection property returns the MediaCollection object. You can only access the properties of the MediaCollection object after you have created it. For example, to add a Media object (a song), type the following:

     player.mediacollection.add('laure.wma')

You have added the file laure.wma to the media collection.

You can get the current Media object by using the currentMedia property of the Player. For example, to get the duration property of the current Media object, type:

     myduration = player.currentmedia.duration

There are many ways to get a Media object so that you can access its properties. For example, if you want to access the duration property of the current media, each of the following lines could be used:

To get the duration of the currently playing media, type:

player.currentMedia.duration

To get the duration of the current media in a playlist, type:

player.controls.currentItem.duration

To get the duration of the third media item in a playlist, type:

player.currentPlaylist.item(2).duration

To get the duration of the third media item in a "Jazz" genre, type:

player.mediaCollection.getByGenre("jazz").item(2).duration

To get the duration of the third media item in the second playlist, type:

player.playlistCollection.getAll.item(1).item(2).duration


About the StringCollection Object

This object governs string collections, which are used to provide string handling capabilities for the MediaCollection object. The StringCollection object can be retrieved through the getAttributeStringCollection method of the MediaCollection object. You can use this to work with string collections representing the values of various media library attributes.


About the Error and ErrorItem Objects

These objects govern the error-handling capabilities of Windows Media Player. The Error object is obtained from the Player through the error property. You can get a specific code from the Error object by using the item property of the Error object to create the ErrorItem object. For example, to get the error code of the first error item, type:

     myerrorcode = player.error.item(0).errorCode

You can also invoke Web Help with the Error object by using the following code:

     player.error.webHelp()


About the ClosedCaption Object

This object governs the captioning interface for Windows Media Player. The ClosedCaption object is obtained through the closedCaption property of the Player object. For example, to get the SAMIFileName property value, type the following:

     myfile = player.closedcaption.SAMIFileName


Methods and Properties

Each object has a set of methods and properties through which the developer can program the Windows Media Player control. A method is a command that tells the control to do something, and a property allows the developer to read or write a particular data value. For example, the Play method starts the content playing, and the frameRate property indicates the current frame rate of the content playing.


Events

The Player object has a set of events that allows the developer to provide alternatives when Windows Media Player performs a specific action. By writing code in an event handler, the developer can run code to respond to specific events inside Windows Media Player. For example, when the content finishes playing, an event handler can ask the user if he or she wants to play it again.


Embedding the Player in the Body Section of a Web Page

The Windows Media Player ActiveX object is embedded in a Web page using the OBJECT element. Unlike earlier versions, the OBJECT element that defines Windows Media Player must be placed in the BODY section of a Web page; that is, between the <BODY> and </BODY> tags. Placing the Windows Media Player ActiveX object in the HEAD section of a Web page can produce unexpected results.

If you put the Windows Media Player ActiveX control in the BODY section of a Web page, the control user interface will be displayed. If you do not want it to be displayed, and wish to create your own user interface, set the height and width attributes of the OBJECT element to zero.


PARAM Tags

Windows Media Player uses the PARAM element to define specific startup conditions for the control. The PARAM element is embedded inside the OBJECT element.

For example, if you want to define whether the autoStart property is True or not, you would embed the PARAM element inside the OBJECT element.

<OBJECT ID="Player"
  CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6">
  <PARAM name="autoStart" value="True">
</OBJECT>

You can have as many PARAM tags in an OBJECT element as you want. PARAM has two attributes, name and value. Both attributes must be set.

The following values are supported for use with the name attribute of the PARAM element.

autoStart

balance

baseURL

captioningID

currentPosition

currrentMarker

defaultFrame

enableContextMenu

enableErrorDialogs

enabled

fullScreen

invokeURLs

mute

playCount

rate

SAMIFilename

SAMILang

SAMIStyle

uiMode

URL

volume

See the Windows Media Player Control Reference for more details about the values for each value attribute.


Player Control Guide

The Microsoft Windows Media Player ActiveX control object model exposes methods, properties, and events for use in Web pages.


Simple Example of Scripting in a Web Page.

You can easily embed the Windows Media Player control in an HTML file using any scripting language your browser recognizes. The following simple example uses Microsoft JScript to create a page that will play a file when you click on a button, and stop playing the file when you click on another button.

You can embed the Windows Media Player ActiveX control in a Web page using the following four steps:

  1. Create the Web page.
  2. Add the OBJECT tag.
  3. Add a user interface. In this case, two buttons.
  4. Add a few lines of code to respond when the user clicks on one of the buttons you have created.

Creating the Web Page

The first step is to create a valid HTML Web page. The following code is the minimum needed to create a blank but valid HTML page:

<HTML>
    <HEAD>
    </HEAD>
    <BODY>
    </BODY>
</HTML>

Adding the OBJECT Tag

Once you have created a Web page, you need to add an OBJECT tag. This identifies the ActiveX control to the browser and sets up any initial definitions. You must place the OBJECT tag in the BODY of the code. If you place it in the BODY, the default user interface of Windows Media Player will be visible. If you want to create your own user interface, set the height and width attributes to 0 (zero). The following code is recommended:

<OBJECT ID="Player" height="0" width="0"
  CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6">
</OBJECT>

The following OBJECT tag attributes are required:

ID

The name that will be used by other parts of the code to identify and use the ActiveX control. You can choose any name you want, as long as it is a name that is not already used by HTML, HTML extensions, or the scripting language you are using. In this example, the name Player is used, but you could also call it MyPlayer or something else. Just pick a name that is unique to that Web page.

CLASSID

A very large hexidecimal number that is unique to the control. Only one control has this number and it is the Windows Media Player ActiveX control. To prevent typograhical errors, you can copy and paste this number from the documentation. Previous versions of the Windows Media Player control had a different CLASSID.

Adding a User Interface

HTML allows a vast wealth of user interface elements, allowing the user to interact with your Web page by clicking, pressing keys, and other user actions. Adding a few INPUT buttons is the easiest way to provide a quick user interface. The following code creates two buttons that can respond to the user. Clicking one button starts the media stream playing and the other button stops it:

<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play" OnClick="StartMeUp()">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop" OnClick="ShutMeDown()">

The name of the button is used to identify the button to your code; the value is the label that will appear on the button, and the OnClick attribute identifies which part of your scripting code will be called when the button is clicked.

Adding Scripting Code

Scripting code adds interactivity to your page. Scripting code can respond to events, call methods, and change run-time properties. Extended scripts are enclosed in a SCRIPT tag set. The SCRIPT tag tells the browser where your scripting code is and identifies the scripting language. If you do not identify a language, the default language will be Microsoft JScript.

It is good authoring practice to enclose your script in HTML comment tags so browsers that do not support scripting do not render your code as text. Put the SCRIPT tag anywhere within the BODY of your HTML file and embed the comment-surrounded code within the opening and closing SCRIPT tags.

The following Microsoft JScript code example calls the Windows Media Player control and performs an appropriate action in response to the corresponding button click.

<SCRIPT>
<!--

function StartMeUp ()
{
    Player.URL = "laure.wma";
}

function ShutMeDown ()
{
    Player.controls.stop();
}

-->
</SCRIPT>

The example function, StartMeUp, is called when the button marked Play is clicked, and the ShutMeDown function is called when the Stop button is clicked.

The code inside StartMeUp uses the URL property to define a path to the media. The media will start playing immediately.

The ShutMeDown code calls the stop method of the Controls object. Note that the Controls object is called through the controls property of the Player object, which has the ID value of "Player".

The following code shows a complete example.

<HTML>
<HEAD>
</HEAD>
<BODY>
<OBJECT ID="Player" height="0" width="0"
  CLASSID="CLSID:6BF52A52-394A-11d3-B153-00C04F79FAA6">
</OBJECT>
<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play" OnClick="StartMeUp()">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop" OnClick="ShutMeDown()">
<SCRIPT>
<!--

function StartMeUp ()
{
    Player.URL = "laure.wma";
}

function ShutMeDown ()
{
    Player.controls.stop();
}

-->
</SCRIPT>
</BODY>
</HTML>

Note that you must provide a valid URL to a valid file name in the URL property. In this case the assumption is that the file "laure.wma" is in the same directory as the HTML file.


Other Samples

To see complete working samples of embedding the Windows Media Player ActiveX control, click the Start button, then point to Programs, then Windows Media, and then click Windows Media Player SDK samples. You must first install the Windows Media Player SDK to use the samples. If you have not already installed it, click the following link:

Install Windows Media Player SDK


Object Model Reference

The Windows Media Player Object Model Reference documents the following objects and their associated methods, properties, and events.

Object | Description
Cdrom | Methods and properties for accessing a CD in its drive.
CdromCollection | Methods and properties for accessing a collection of CDs.
ClosedCaption | Properties for including captions with a media clip.
Controls | Methods and properties representing the transport controls of Windows Media Player such as Play, Stop and Pause.
DVD | Property, methods, and events for working with DVDs.
Error | Methods and properties providing access to a collection of ErrorItem objects.
ErrorItem | Properties providing information on errors.
Media | Methods and properties relating to multimedia clips.
MediaCollection | Methods providing access to a collection of Media objects.
Network | Properties relating to the network connection of Windows Media Player.
Player | Methods, properties, and events that Windows Media Player can be programmed to respond to.
Playlist | Methods and properties for manipulating lists of media clips.
PlaylistArray | A method and a property for accessing a collection of Playlist objects by index number.
PlaylistCollection | Methods for organizing a collection of Playlist objects.
Settings | Properties allowing the specification or retrieval of Windows Media Player settings.
StringCollection | A method and a property for manipulating collections of strings.


Cdrom Object

The Cdrom object provides a way to access a CD in its drive.

The Cdrom object supports the following properties.

Property | Description
driveSpecifier | Retrieves the CD-ROM drive letter.
playlist | Retrieves a Playlist object representing the tracks on the CD currently in the CD-ROM drive.

The Cdrom object supports the following method.

Method | Description
eject | Ejects the CD from the CD-ROM drive.

The Cdrom object is accessed through the following method.

Object | Method
CdromCollection | item

For purposes of illustration, player.cdromCollection.item(index) is used in the reference syntax sections.


Cdrom.driveSpecifier

The driveSpecifier property retrieves the CD-ROM drive letter.

Syntax

player.cdromCollection.item(index).driveSpecifier

Possible Values

This property is a read-only String.

See Also

  • Cdrom Object


Cdrom.eject

The eject method ejects the CD from the CD-ROM drive.

Syntax

player.cdromCollection.item(index).eject()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

The CD must not be playing when this method is called. To confirm that this is true, check the value of Player.playState.

See Also

  • Cdrom Object
  • Player.playState


Cdrom.playlist

The playlist property retrieves a Playlist object representing the tracks on the CD currently in the CD-ROM drive.

Syntax

player.cdromCollection.item(index).playlist

Possible Values

This property is a read-only Playlist object.

See Also

  • Cdrom Object


CdromCollection Object

The CdromCollection object provides a way to organize and access a collection of CD-ROM drives.

The CdromCollection object supports the following property.

Property | Description
count | Retrieves the number of available CD-ROM drives on the system.

The CdromCollection object supports the following methods.

Method | Description
getByDriveSpecifier | Retrieves the Cdrom object associated with a particular drive letter.
item | Retrieves the Cdrom object at the given index.

The CdromCollection object is accessed through the following property.

Object Property


CdromCollection.count

The count property retrieves the number of available CD-ROM drives on the system.

Syntax

player.cdromCollection.count

Possible Values

This property is a read-only Number (long).

See Also

  • CdromCollection Object


CdromCollection.getByDriveSpecifier

The getByDriveSpecifier method retrieves the Cdrom object associated with a particular drive letter.

Syntax

player.cdromCollection.getByDriveSpecifier(driveSpecifier)

Parameters

driveSpecifier

String containing the drive letter.

Return Values

This method returns a Cdrom object.

See Also

  • CdromCollection Object


CdromCollection.item

The item method retrieves the Cdrom object at the given index.

Syntax

player.cdromCollection.item(index)

Parameters

index

Number (long) containing the index.

Return Values

This method returns a Cdrom object.

See Also

  • CdromCollection Object


ClosedCaption Object

The ClosedCaption object provides a way to include captions with a media clip.

The ClosedCaption object supports the following properties.

Property | Description
captioningID | Specifies or retrieves the name of the frame or control displaying the captioning.
SAMIFileName | Specifies or retrieves the name of the file containing the information needed for closed captioning.
SAMILang | Specifies or retrieves the language displayed for closed captioning.
SAMIStyle | Specifies or retrieves the closed captioning style.

The ClosedCaption object is accessed through the following property.

Object Property


ClosedCaption.captioningID

The captioningID property specifies or retrieves the name of the frame or control displaying the captioning.

Syntax

player.closedCaption.captioningID

Possible Values

This property is a read/write String.

See Also

  • ClosedCaption Object


ClosedCaption.SAMIFileName

The SAMIFileName property specifies or retrieves the name of the file containing the information needed for closed captioning.

Syntax

player.closedCaption.SAMIFileName

Possible Values

This property is a read/write String.

Remarks

The Synchronized Accessible Media Interchange (SAMI) file must use an .smi or .sami file extension.

See Also

  • ClosedCaption Object


ClosedCaption.SAMILang

The SAMILang property specifies or retrieves the language displayed for closed captioning.

Syntax

player.closedCaption.SAMILang

Possible Values

This property is a read/write String.

Remarks

A Synchronized Accessible Media Interchange (SAMI) file can contain text for one or many languages. The languages available for closed captioning are defined between the <STYLE> and </STYLE> tags in the SAMI file. A language is specified with a unique alphanumeric string that is preceded by a period (.). For example, .ENUSCC could be used to define US English.

If no SAMI language is specified, the first language defined in the SAMI file is used by default.

See Also

  • ClosedCaption Object


ClosedCaption.SAMIStyle

The SAMIStyle property specifies or retrieves the closed captioning style.

Syntax

player.closedCaption.SAMIStyle

Possible Values

This property is a read/write String.

Remarks

A Synchronized Accessible Media Interchange (SAMI) file can contain several format style definitions. SAMI styles are defined between the <STYLE> and </STYLE> tags in the SAMI file. A style is defined with a text string preceded by a pound sign (#). For example, #BigFont specifies a style that can be used with a larger font.

If no SAMI style is specified, the first style defined in the SAMI file is used by default.

See Also

  • ClosedCaption Object


Controls Object

The Controls object provides a way to manipulate the playback of media using the following properties and methods.

The Controls object supports the following properties.

Property | Description
currentItem | Specifies or retrieves the current media item.
currentMarker | Specifies or retrieves the current marker number.
currentPosition | Specifies or retrieves the current position in the media item in seconds from the beginning.
currentPositionString | Retrieves the current position in the media item as a String.

The Controls object supports the following methods.

Method | Description
fastForward | Starts fast play of the media item in the forward direction.
fastReverse | Starts fast play of the media item in the reverse direction.
isAvailable | Determines whether a specified type of information is available or a given action can be performed.
next | Sets the current item to the next item in the playlist.
pause | Pauses the playing of the media item.
play | Causes the media item to start playing.
playItem | Causes the current media item to start playing, or resumes play of a paused item.
previous | Sets the current item to the previous item in the playlist.
stop | Stops the playing of the media item.

The Controls object is accessed through the following property.

Object Property


Controls.currentItem

The currentItem property specifies or retrieves the current media item.

Syntax

player.controls.currentItem

Possible Values

This property is a read/write Media object.

See Also

  • Controls Object
  • Media Object


Controls.currentMarker

The currentMarker property specifies or retrieves the current marker number.

Syntax

player.controls.currentMarker

Possible Values

This property is a read/write Number (long) with a default value of zero.

Remarks

Setting currentMarker causes playback to start from the specified marker. Before attempting to set currentMarker, determine whether a file has markers and how many it has by using markerCount. If a file has no markers, setting currentMarker to anything but zero results in an error. Setting currentMarker to a number higher than markerCount also results in an error.

The currentMarker property always returns the current or last marker, which means the actual file position can be either at the current marker or before the next marker. Markers are numbered beginning at 1, so if a file has markers, you can set currentMarker to zero to change the file position to zero.

Before the current media item is set (using Player.URL or Player.currentMedia), currentMarker returns zero.

See Also

  • Controls Object
  • Media.markerCount
  • Player.currentMedia
  • Player.URL


Controls.currentPosition

The currentPosition property specifies or retrieves the current position in the media item in seconds from the beginning.

Syntax

player.controls.currentPosition

Possible Values

This property is a read/write Number (double).

See Also

  • Controls Object


Controls.currentPositionString

The currentPositionString property retrieves the current position in the media item as a String formatted as HH:MM:SS (hours, minutes, and seconds).

Syntax

player.controls.currentPositionString

Possible Values

This property is a read-only String.

Remarks

If the media item is less than an hour long, the HH: portion is not included.

See Also

  • Controls Object


Controls.fastForward

The fastForward method starts fast play of the media item in the forward direction.

Syntax

player.controls.fastForward()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

The fastForward method plays the clip back at five times the normal speed. Invoking fastForward changes the Settings.rate property to 5.0. If rate is subsequently changed, or if play or stop is called, Windows Media Player will cease fast forwarding.

The fastForward method does not work for audio files, live broadcasts, and certain media file types. To determine whether you can fast forward in a clip, call isAvailable(“FastForward”).

See Also

  • Controls Object
  • Controls.isAvailable
  • Controls.play
  • Controls.stop
  • Settings.rate


Controls.fastReverse

The fastReverse method starts fast play of the media item in the reverse direction.

Syntax

player.controls.fastReverse()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

The fastReverse method plays the clip in reverse at five times the normal speed. Invoking fastReverse changes the Settings.rate property to –5.0. If rate is subsequently changed, or if play or stop is called, Windows Media Player will cease fast reverse.

If the item is part of a playlist, fastReverse stops at the beginning of the current track. For instance, if track 3 is in fastReverse, when the beginning of track 3 is reached, Windows Media Player will not go to track 2. The Settings.playCount property is ignored for fastReverse.

If you call fastForward while fastReverse is in effect, fastReverse will be stopped and fastForward will begin.

This method does not work for live broadcasts and certain media types. To determine whether you can use fast reverse in a clip, call isAvailable(“FastReverse”).

See Also

  • Controls Object
  • Controls.fastForward
  • Controls.isAvailable
  • Controls.play
  • Controls.stop
  • Settings.rate


Controls.isAvailable

The isAvailable method determines whether a specified type of information is available or a given action can be performed.

Syntax

player.controls.isAvailable(name)

Parameters

name

String containing one of the following values.

String | Description
Play | Determines whether the play method is available.
Pause | Determines whether the pause method is available.
Stop | Determines whether the stop method is available.
FastForward | Determines whether the file supports fast forwarding and whether that functionality can be invoked. Many file types (or live streams) do not support FastForward.
FastReverse | Determines whether the file supports FastReverse and whether that functionality can be invoked. Many file types (or live streams) do not support FastReverse.
Next | Determines whether the user can seek to the next entry in a playlist.
Previous | Determines whether the user can seek to the previous entry in a playlist.
CurrentMarker | Determines whether the user can seek to a specific named marker. Only valid for a file which has markers.
CurrentPosition | Determines whether the user can seek to a specific position in the file. Some files do not support seeking.
CurrentItem | Determines whether the user can set the currentItem property.

Return Values

This method returns a Boolean value.

See Also

  • Controls Object


Controls.next

The next method sets the current item to the next item in the playlist.

Syntax

player.controls.next()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the playlist is on the last entry when next is invoked, the first entry in the playlist will become the current one.

See Also

  • Controls Object
  • Controls.previous
  • Controls.stop


Controls.pause

The pause method pauses the playing of the media item.

Syntax

player.controls.pause()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

When a file is paused, Windows Media Player does not give up any system resources, such as the audio device.

See Also

  • Controls Object


Controls.play

The play method causes the current media item to start playing, or resumes play of a paused item.

Syntax

player.controls.play()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • Controls Object


Controls.playItem

The playItem method plays the specified media item.

Syntax

player.controls.playItem(theMediaItem)

Parameters

theMediaItem

Media object to be played.

Return Values

This method does not return a value.

Remarks

The media item will be loaded and played automatically, regardless of the value of the Settings.autoStart property. To load an item without playing it automatically, assign a value to Player.URL, after which Controls.play can be called to start playing the item.

Note   playItem works only with items in currentPlaylist. Calling playItem with a reference to a saved media item is not supported.

See Also

  • Controls Object


Controls.previous

The previous method sets the current item to the previous item in the playlist.

Syntax

player.controls.previous()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the playlist is on the first entry when previous is invoked, the last entry in the playlist will become the current one.

See Also

  • Controls Object
  • Controls.next
  • Controls.stop


Controls.stop

The stop method stops the playing of the media item.

Syntax

player.controls.stop()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

This method causes Windows Media Player to release any system resources it is using, such as the audio device.

When the player is stopped, the track rewinds to the beginning. Calling play will then begin playback of the clip from the beginning. To halt a play operation without changing the current position, use the pause method.

See Also

  • Controls Object
  • Controls.next
  • Controls.pause
  • Controls.previous


Error Object

The Error object provides access to a collection of ErrorItem objects.

The Error object supports the following properties.

Property | Description
errorCount | Retrieves the number of errors in the error queue.

The Error object supports the following methods.

Method | Description
clearErrorQueue | Clears the errors from the error queue.
item | Retrieves an ErrorItem object from the error queue.
webHelp | Launches the Microsoft Windows Media Player Web Help page to display further information about the error.

The Error object is accessed through the following property.

Object Property


Error.clearErrorQueue

The clearErrorQueue method clears the errors from the error queue.

Syntax

player.error.clearErrorQueue()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

This method is useful to clear the error queue after a series of errors has been processed.

See Also

  • Error Object


Error.errorCount

The errorCount property retrieves the number of errors in the error queue.

Syntax

player.error.errorCount

Possible Values

This property is a read-only Number (long).

See Also

  • Error Object


Error.item

The item method retrieves an ErrorItem object from the error queue.

Syntax

player.error.item(index)

Parameters

index

Number (long) containing the index of the ErrorItem object to be retrieved.

Return Values

This method returns an ErrorItem object.

Remarks

Windows Media Player can generate a number of errors in response to an error condition. This method allows the retrieval of a specific error in the queue using an index number. The index numbers for the error queue begin with zero.

See Also

  • Error Object
  • ErrorItem Object


Error.webHelp

The webHelp method launches the Microsoft Windows Media Player Web Help page to display further information about the error.

Syntax

player.error.webHelp()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

The Web Help pages always contain the latest and most detailed information about Windows Media Player errors. This method automatically transfers the other information needed by Web Help, such as the operating system version being used.

See Also

  • Error Object


ErrorItem Object

The ErrorItem object provides a way to access error information.

The ErrorItem object supports the following properties.

Property | Description
customURL | Reserved for future use.
errorCode | Retrieves the current error code.
errorContext | Reserved for future use.
errorDescription | Retrieves a description of the error.
remedy | Reserved for future use.

The ErrorItem object is accessed through the following method.

Object | Method
Error | item

For purposes of illustration, player.error.item(index) is used in the reference syntax sections.


ErrorItem.errorCode

The errorCode property retrieves the current error code.

Syntax

player.error.item(index).errorCode

Possible Values

This property is a read-only Number (long).

See Also

  • ErrorItem Object


ErrorItem.errorDescription

The errorDescription property retrieves a description of the error.

Syntax

player.error.item(index).errorDescription

Possible Values

This property is a read-only String.

See Also

  • ErrorItem Object


Media Object

The Media object provides a way to specify or retrieve properties of a multimedia clip, using the following properties and methods.

The Media object supports the following properties.

Property | Description
attributeCount | Retrieves the number of attributes that can be queried and/or set for the media item.
duration | Retrieves the duration in seconds of the current media item.
durationString | Retrieves a String value indicating the duration of the current media item in HH:MM:SS format.
imageSourceHeight | Retrieves the height of the current media item in pixels.
imageSourceWidth | Retrieves the width of the current media item in pixels.
markerCount | Retrieves the number of markers in the media item.
name | Specifies or retrieves the name of the media item.
sourceURL | Retrieves the URL of the current media item.

The Media object supports the following methods.

Method | Description
getAttributeName | Retrieves the name of the attribute corresponding to the specified index.
getItemInfo | Retrieves the value of the specified attribute for the current media item.
getItemInfoByAtom | Retrieves the value of the attribute with the specified index number.
getMarkerName | Retrieves the name of the marker at the specified index.
getMarkerTime | Retrieves the time of the marker at the specified index.
isIdentical | Retrieves a value indicating whether the supplied object is the same as the current one.
isMemberOf | Retrieves a value indicating whether the specified media item is a member of the specified playlist.
isReadOnlyItem | Retrieves a value indicating whether the attributes of the specified media item can be edited.
setItemInfo | Sets the value of the specified attribute for the media item.

The Media object is accessed through the following properties and methods.

Object | Property or method
Controls | currentItem
Player | currentMedia
Playlist | item

Because it is the most common means of access, player.currentMedia is used for purposes of illustration in the reference syntax sections.


Media.attributeCount

The attributeCount property retrieves the number of attributes that can be queried and/or set for the media item.

Syntax

player.currentMedia.attributeCount

Possible Values

This property is a read-only Number (long).

Example

Please see the Playlist.attributeCount property for a sample illustrating the use of this property.

See Also

  • Media Object


Media.duration

The duration property retrieves the duration of the current media item in seconds.

Syntax

player.currentMedia.duration

Possible Values

This property is a read-only Number (double).

Remarks

If this property is used with a media item other than the one specified in Player.currentMedia, it will not contain a valid value.

See Also

  • Media Object
  • Player.currentMedia


Media.durationString

The durationString property retrieves a String value indicating the duration of the current media item in HH:MM:SS format.

Syntax

player.currentMedia.durationString

Possible Values

This property is a read-only String.

Remarks

If this property is used with a media item other than the one specified in Player.currentMedia, it will not contain a valid value. If the media item is less than an hour long, the HH: portion of the return value is omitted.

See Also

  • Media Object
  • Player.currentMedia


Media.getAttributeName

The getAttributeName method retrieves the name of the attribute corresponding to the specified index.

Syntax

player.currentMedia.getAttributeName(index)

Parameters

index

Number (long) containing the index of the attribute.

Return Values

This method returns a String specifying the name of the attribute.

Remarks

The attribute name returned can be used in conjunction with getItemInfo to retrieve the value for a specific named attribute.

Example

Please see the Playlist.attributeCount property for a sample illustrating the use of this property.

See Also

  • Media Object
  • Media.attributeCount
  • Media.getItemInfo


Media.getItemInfo

The getItemInfo method retrieves the value of the specified attribute for the current media item.

Syntax

player.currentMedia.getItemInfo(attribute)

Parameters

attribute

String containing the attribute name.

Return Values

This method returns a String representing the value of the specified attribute.

Remarks

This is the method used to retrieve metadata information about a specific piece of media content, whether it stands alone or is part of a playlist.

The attributeCount property can be used to determine the number of attributes available for a given Media object. Index numbers can then be used with the getAttributeName method to determine the names of the attributes, which can in turn be passed to getItemInfo. Alternately, the value of an attribute can be retrieved directly from the index number using the getItemInfoByAtom method.

Example

Please see the Playlist.attributeCount property for a sample illustrating the use of this property.

See Also

  • Media Object
  • Media.attributeCount
  • Media.GetItemInfoByAtom
  • Media.SetItemInfo


Media.getItemInfoByAtom

The getItemInfoByAtom method retrieves the value of the attribute with the specified index number.

Syntax

player.currentMedia.getItemInfoByAtom(atom)

Parameters

atom

Number (long) specifying the index.

Return Values

This method returns a String.

Remarks

This method can be used to retrieve metadata information about a specific piece of media using an index number. The attributeCount property can be used to determine the number of attributes available for the media item. The getMediaAtom method of the MediaCollection object can also be used to retrieve the index of a particular media library attribute. This technique is generally more efficient than the getItemInfo method when working with large playlists.

See Also

  • Media Object
  • Media.attributeCount
  • Media.GetItemInfo
  • Media.SetItemInfo
  • MediaCollection.getMediaAtom


Media.getMarkerName

The getMarkerName method retrieves the name of the marker at the specified index.

Syntax

player.currentMedia.getMarkerName(markerNum)

Parameters

markerNum

Number specifying a marker index.

Return Values

This method returns a String.

Remarks

This method returns NULL if the specified marker does not exist.

Some media clips do not contain markers. Use markerCount to find out how many markers are in the current clip.

Marker index numbers start at 1.

See Also

  • Media Object
  • Media.getMarkerTime
  • Media.markerCount


Media.getMarkerTime

The getMarkerTime method retrieves the time of the marker at the specified index.

Syntax

player.currentMedia.getMarkerTime(markerNum)

Parameters

markerNum

Number (long) specifying the marker index.

Return Values

This method returns a Number (double) specifying the location of the marker in seconds from the beginning of the clip.

Remarks

This method returns NULL if the specified marker does not exist.

Some media clips do not contain markers. Use markerCount to find out how many markers are in the current clip.

Marker index numbers start at 1.

See Also

  • Media Object
  • Media.GetMarkerName
  • Media.markerCount


Media.imageSourceHeight

The ImageSourceHeight property retrieves the height of the current media item in pixels.

Syntax

player.currentMedia.imageSourceHeight

Possible Values

This property is a read-only Number (long).

Remarks

If currentMedia is not set, this property returns zero.

See Also

  • Media Object
  • Player.currentMedia


Media.imageSourceWidth

The imageSourceWidth property retrieves the width of the current media item in pixels.

Syntax

player.currentMedia.imageSourceWidth

Possible Values

This property is a read-only Number (long).

Remarks

If currentMedia is not set, this property returns zero.

See Also

  • Media Object
  • Player.currentMedia


Media.isIdentical

The isIdentical method retrieves a value indicating whether the supplied object is the same as the current one.

Syntax

player.currentMedia.isIdentical(theMedia)

Parameters

theMedia

Media object to compare with the current one.

Return Values

This method returns a Boolean.

See Also

  • Media Object


Media.isMemberOf

The isMemberOf method returns a value indicating whether the media item is a member of the specified playlist.

Syntax

player.currentMedia.isMemberOf(playlist)

Parameters

playlist

Playlist object that might contain the media item.

Return Values

This method returns a Boolean.

Remarks

This method is not supported with playlists retrieved through the MediaCollection object. To test whether a media item is a member of a particular named playlist, retrieve the playlist with player.playlistCollection.getByName(name).item(0). This method can also be used with CD and metafile playlists.

See Also

  • Media Object
  • Playlist Object
  • PlaylistCollection Object


Media.isReadOnlyItem

The isReadOnlyItem method returns a value indicating whether the specified attribute of the media item can be edited.

Syntax

player.currentMedia.isReadOnlyItem(attribute)

Parameters

attribute

String indicating the name of the attribute to test.

Return Values

This method returns a Boolean.

Remarks

If an attribute is read-only then it cannot be set with the setItemInfo method.

See Also

  • Media Object
  • Media.setItemInfo


Media.markerCount

The markerCount property retrieves the number of markers in the media item.

Syntax

player.currentMedia.markerCount

Possible Values

This property is a read-only Number (long) specifying the number of markers in the file.

Remarks

This property returns zero if a file has no markers, or if the Player.currentMedia or Player.URL property is not set. Marker numbers start at 1.

See Also

  • Media Object
  • Player.currentMedia


Media.name

The name property specifies or retrieves the name of the media item.

Syntax

player.currentMedia.name

Possible Values

This property is a read/write String containing the name of the media item.

See Also

  • Media Object


Media.setItemInfo

The setItemInfo method sets the value of the specified attribute for the current media item.

Syntax

player.currentMedia.setItemInfo(attribute, value)

Parameters

attribute

String containing the attribute name.

value

String containing the new value.

Return Values

This method does not return a value.

Remarks

Before using this method, use the isReadOnlyItem method to determine if a particular attribute can be set.

Example

Please see the Playlist.attributeCount property for a sample illustrating the use of this property.

See Also

  • Media Object
  • Media.GetItemInfoByAtom
  • Media.GetItemInfo
  • Media.isReadOnlyItem


Media.sourceURL

The sourceURL property retrieves the URL of the current media item.

Syntax

player.currentMedia.sourceURL

Possible Values

This property is a read-only String.

See Also

  • Media Object


MediaCollection Object

The MediaCollection object provides a way to organize a large collection of media items. It can be queried to generate playlists automatically.

The MediaCollection object supports the following methods.

Method | Description
add | Adds a new media item to the media library.
getAll | Retrieves a Playlist object containing all media items in the media library.
getAttributeStringCollection | Retrieves a StringCollection object representing the set of all values for a given attribute within a given media type.
getByAlbum | Retrieves a Playlist object containing media items from the specified album.
getByAttribute | Retrieves a Playlist object containing media items with the specified attribute having the specified value.
getByAuthor | Retrieves a Playlist object containing media items by the specified author.
getByGenre | Retrieves a Playlist object containing media items with the specified genre.
getByName | Retrieves a Playlist object containing media items with the specified name.
getMediaAtom | Retrieves the index at which a given property resides within the set of available properties.
isDeleted | Retrieves a value indicating whether the specified media item is in the deleted items folder.
remove | Removes an item from the media collection.
setDeleted | Moves the specified media item to the deleted items folder.

The MediaCollection object is accessed through the following property.

Object Property


MediaCollection.add

The add method adds a new media item to the media library.

Syntax

player.mediaCollection.add(URL)

Parameters

URL

String containing the URL.

Return Values

This method returns a Media object.

Remarks

This method loads an existing media item into the content database, given a URL.

See Also

  • MediaCollection Object
  • MediaCollection.remove


MediaCollection.getAll

The getAll method retrieves a playlist containing all media items in the media library.

Syntax

player.mediaCollection.getAll()

Parameters

This method takes no parameters.

Return Values

This method returns a Playlist object.

Remarks

Because the media library usually contains a large number of media items, this method is extremely slow and should be used with caution.

See Also

  • MediaCollection Object


MediaCollection.getAttributeStringCollection

The getAttributeStringCollection method retrieves a StringCollection object representing the set of all values for a given attribute within a given media type.

Syntax

player.mediaCollection.getAttributeStringCollection(attribute, mediaType)

Parameters

attribute

String specifying the attribute. Contains one of the following values: “Album”, “Author”, “Artist”, or “Genre”.

mediaType

String representing the media type. Contains one of the following values: “Audio” or “Video”.

Return Values

This method returns a StringCollection object.

See Also

  • MediaCollection Object
  • StringCollection Object


MediaCollection.getByAlbum

The GetByAlbum method retrieves a playlist containing the media items from the specified album.

Syntax

player.mediaCollection.getByAlbum(album)

Parameters

album

String containing the name of the album.

Return Values

This method returns a Playlist object.

See Also

  • MediaCollection Object


MediaCollection.getByAttribute

The getByAttribute method retrieves a playlist of media items with the specified attribute having the specified value.

Syntax

player.mediaCollection.getByAttribute(attribute, value)

Parameters

attribute

String indicating the name of the attribute to search on. Contains one of the following values: Artist, Author, Genre, Album.

value

String indicating the value that the attribute should have.

Return Values

This method returns a Playlist object.

Remarks

This method can be used to create a generic query for media items that match a value for an attribute in the database. This is especially useful in the case of user-defined attributes. If the attribute does not exist, an error will result.

See Also

  • MediaCollection Object


MediaCollection.getByAuthor

The getByAuthor method retrieves a playlist of the media items by the specified author.

Syntax

player.mediaCollection.getByAuthor(author)

Parameters

author

String containing the name of the author.

Return Values

This method returns a Playlist object.

See Also

  • MediaCollection Object


MediaCollection.getByGenre

The getByGenre method retrieves a playlist of the media items with the specified genre.

Syntax

player.mediaCollection.getByGenre(genre)

Parameters

genre

String containing the name of the genre.

Return Values

This method returns a Playlist object.

See Also

  • MediaCollection Object


MediaCollection.getByName

The getByName method retrieves a playlist of the media items with the specified name.

Syntax

player.mediaCollection.getByName(name)

Parameters

name

String containing the name.

Return Values

This method returns a Playlist object.

See Also

  • MediaCollection Object


MediaCollection.getMediaAtom

The getMediaAtom method retrieves the index at which a given attribute resides within the set of available attributes.

Syntax

player.mediaCollection.getMediaAtom(attribute)

Parameters

attribute

String containing the attribute name. Must contain one of the following values.

Value | Description
Album | The name of the album. Used with media items only.
Artist | The name of the artist. Not used with user-created Playlists.
Author | The name of the artist.
Bitrate | The bit rate of the content. Used only with media items from the media library.
Copyright | The copyright of the Playlist item. Not used with CD playlists or media items.
CreationDate | The date and time that the entry in the media library was created. Used only with items from the media library.
DigitallySecure | Indicates whether the item is protected with Digital Rights Management. Used only with media items from the media library.
Genre | The genre of the Playlist item. Not used with playlists from CDs.
MediaType | The type of the media item (audio or video).
Name | The name of the Playlist item.
PlayCount | The number of times the content has been played through to the end. Used only with media items from the media library.
SourceURL | The path or URL to the content. Used only with media items from the media library.
TOC | If applicable, the corresponding CD Table of Contents Indentifier. Not used with user-created Playlists.

Return Values

This method returns a Number (long).

Remarks

This method can be used in conjunction with Media.getItemInfoByAtom in order to retrieve metadata information about a specific media item.

See Also

  • MediaCollection Object
  • Media.getItemInfoByAtom


MediaCollection.isDeleted

The isDeleted method retrieves a value indicating whether the specified media item is in the deleted items folder.

Syntax

player.mediaCollection.isDeleted(item)

Parameters

item

Media object that might be deleted.

Return Values

This method returns a Boolean.

See Also

  • MediaCollection Object


MediaCollection.remove

The remove method removes an item from the media collection.

Syntax

player.mediaCollection.remove(item, delete)

Parameters

item

Media object to be removed.

delete

Boolean indicating whether to delete the media item.

Return Values

This method does not return a value.

Remarks

This method deletes an item from the content index. It also deletes the file from the hard drive if the file is local. The user is presented with a confirmation dialog box to determine whether he wants the item deleted from the database and from the local disk.

See Also

  • MediaCollection Object
  • MediaCollection.add


MediaCollection.setDeleted

The setDeleted method moves the specified media item to the deleted items folder.

Syntax

player.mediaCollection.setDeleted(item)

Parameters

item

Media object being moved.

Return Values

This method returns a Boolean indicating whether the item was successfully moved.

See Also

  • MediaCollection Object


Network Object

The Network object provides properties and methods used to access statistics relating to the quality of a network connection, and to specify and retrieve the network proxy settings.

The Network object supports the following properties.

Property | Description
bandWidth | Retrieves the current bandwidth of the clip.
bitRate | Retrieves the current bit rate being received.
bufferingCount | Retrieves the number of times buffering occurred during clip playback.
bufferingProgress | Retrieves the percentage of buffering completed.
bufferingTime | Specifies or retrieves the amount of buffering time in milliseconds before playing begins.
downloadProgress | Retrieves the percentage of download completed.
encodedFrameRate | Retrieves the video frame rate specified by the content author.
frameRate | Retrieves the current video frame rate in frames per second.
framesSkipped | Retrieves the total number of frames skipped during playback.
lostPackets | Retrieves the number of packets lost.
maxBandwidth | Specifies or retrieves the maximum allowed bandwidth.
receivedPackets | Retrieves the number of packets received.
receptionQuality | Retrieves the percentage of packets received in the last 30 seconds.
recoveredPackets | Retrieves the number of recovered packets.
sourceProtocol | Retrieves the source protocol used to receive data.

The Network object supports the following methods.

Method | Description
getProxyBypassForLocal | Retrieves a value indicating whether the proxy server should by bypassed if the origin server is on a local network.
getProxyExceptionList | Retrieves the proxy exception list.
getProxyName | Retrieves the name of a proxy server to use.
getProxyPort | Retrieves the proxy port to use.
getProxySettings | Retrieves the proxy setting for a given protocol.
setProxyBypassForLocal | Specifies a value indicating whether the proxy server should by bypassed if the origin server is on a local network.
setProxyExceptionList | Specifies the proxy exception list.
setProxyName | Specifies the name of a proxy server to use.
setProxyPort | Specifies the proxy port to use.
setProxySettings | Specifies the proxy setting for a given protocol.

The Network object is accessed through the following property.

Object Property


Network.bandWidth

The bandWidth property retrieves the current bandwidth of the clip.

Syntax

player.network.bandWidth

Possible Values

This property is a read-only Number (long).

Remarks

This property returns zero if the Player.URL property is not set. This property is only valid for streaming media.

See Also

  • Network Object
  • Player.URL


Network.bitRate

The bitRate property retrieves the current bit rate being received.

Syntax

player.network.bitRate

Possible Values

This property is a read-only Number (long).

Remarks

This value is a combination of the bit rates of both the current video and audio streams.

See Also

  • Network Object


Network.bufferingCount

The bufferingCount property retrieves the number of times buffering occurred during clip playback.

Syntax

player.network.bufferingCount

Possible Values

This property is a read-only Number (long).

Remarks

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time when the Player.URL property is set.

See Also

  • Network Object
  • Player.URL


Network.bufferingProgress

The bufferingProgress property retrieves the percentage of buffering completed.

Syntax

player.network.bufferingProgress

Possible Values

This property is a read-only Number (long).

Remarks

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time, when the Player.URL property is set.

See Also

  • Network Object
  • Player.URL


Network.bufferingTime

The bufferingTime property specifies or retrieves the amount of time in milliseconds allocated for buffering incoming data before playing begins.

Syntax

player.network.bufferingTime

Possible Values

This property is a read/write Number (double) ranging from zero to 30,000 with a default value of 5,000.

See Also

  • Network Object


Network.downloadProgress

The downloadProgress property retrieves the percentage of download completed.

Syntax

player.network.downloadProgress

Possible Values

This property is a read-only Number (long).

Remarks

When the Windows Media Player control is connected to a media file that can be played and downloaded at the same time, the downloadProgress property returns the percentage of the total file that has been downloaded. This feature is currently supported only on Web servers. The following file formats can be downloaded and played simultaneously: ASF, WMA, WMV, WM, MP3, MPEG, WAV, and some AVI files.

See Also

  • Network Object


Network.encodedFrameRate

The frameRate property retrieves the video frame rate specified by the content author in frames per second.

Syntax

player.network.videoFrameRate

Possible Values

This property is a read-only Number (long).

See Also

  • Network Object


Network.frameRate

The frameRate property retrieves the current video frame rate in frames per second.

Syntax

player.network.frameRate

Possible Values

This property is a read-only Number (long).

See Also

  • Network Object


Network.framesSkipped

The framesSkipped property retrieves the total number of frames skipped during playback.

Syntax

player.network.framesSkipped

Possible Values

This property is a read-only Number (long).

See Also

  • Network Object


Network.getProxyBypassForLocal

The getProxyBypassForLocal method retrieves a value indicating whether the proxy server is bypassed if the origin server is on a local network.

Syntax

player.network.getProxyBypassForLocal(protocol)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

Return Values

This method returns a Boolean indicating whether the proxy server is bypassed. The value returned is meaningful only when getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object
  • Network.getProxySettings


Network.getProxyExceptionList

The getProxyExceptionList method retrieves the proxy exception list.

Syntax

player.network.getProxyExceptionList(protocol)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

Return Values

This method returns a String specifying a comma-delimited list of hosts for which the proxy server is bypassed. The value returned is meaningful only when getProxySettings returns a value of two (use manual settings).

Remarks

This is a list of computers, domains, and/or addresses that will bypass the proxy server when the host portion of the target URL matches an entry in the list.

Wildcards can be used in the list entries via the “*” character. For example, “*.com” would match all hosts in the “com” domain while “67.*” would match all hosts in the 67 class A subnet.

See Also

  • Network Object
  • Network.getProxySettings


Network.getProxyName

The getProxyName method retrieves the name of the proxy server being used.

Syntax

player.network.getProxyName(protocol)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

Return Values

This method returns a String containing the name of the proxy server being used. The value returned is meaningful only when getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object
  • Network.getProxySettings


Network.getProxyPort

The getProxyPort method retrieves the proxy port being used.

Syntax

player.network.getProxyPort(protocol)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

Return Values

This method returns a Number (long) containing the proxy port being used. The value returned is meaningful only when getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object
  • Network.getProxySettings


Network.getProxySettings

The getProxySettings method retrieves the proxy setting for a given protocol.

Syntax

player.network.getProxySettings(protocol)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

Return Values

This method returns a Number (long) containing one of the following values.

Value | Description
0 | A proxy server is not being used.
1 | The proxy settings for the current browser are being used (only valid for HTTP).
2 | The manually specified proxy settings are being used.
3 | The proxy settings are being auto-detected.

See Also

  • Network Object


Network.lostPackets

The lostPackets property retrieves the number of packets lost.

Syntax

player.network.lostPackets

Possible Values

This property is a read-only Number (long).

Remarks

This property is only valid for streaming media, and will equal zero when using the HTTP protocol, which is lossless.

Packets may be lost for a number of reasons, such as the type and quality of the network connection.

Each time playback is stopped and restarted, this property is set to zero. It is not reset if playback is paused and restarted. This property returns valid information only during run time, and only if the Player.URL property is set.

See Also

  • Network Object
  • Player.URL


Network.maxBandwidth

The maxBandwidth property specifies or retrieves the maximum allowed bandwidth.

Syntax

player.network.maxBandwidth

Possible Values

This property is a read/write Number (long).

Remarks

This property has no default value. The player attempts to achieve the highest bandwidth possible. Only in the case of the value being set will any throttling occur.

This setting is useful for throttling the amount of bandwidth used, particularly in the case of an MBR stream. An MBR stream contains multiple streams with different bit rates. In some cases, it may be desirable to use a stream with a lower bit rate than the client requires. In this case, setting the maxBandwidth property will select a lower bit-rate stream. For example, assume that an MBR stream includes streams encoded at 20Kbps, 37Kbps and 200Kbps. The user’s machine has a T1 connection. However, if the desire is to use much less bandwidth than is available, setting the maxBandwidth property to 50,000 (50Kbps) will select the 37Kbps stream instead of the 200Kbps stream.

See Also

  • Network Object


Network.receivedPackets

The receivedPackets property retrieves the number of packets received.

Syntax

player.network.receivedPackets

Possible Values

This property is a read-only Number (long).

Remarks

Each time clip playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

See Also

  • Network Object


Network.receptionQuality

The receptionQuality property retrieves the percentage of packets received in the last 30 seconds.

Syntax

player.network.receptionQuality

Possible Values

This property is a read-only Number (long).

Remarks

The number of packets received, lost, and recovered during streaming is monitored every second. receptionQuality is the percentage of packets not lost during the last 30 seconds.

Each time file playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

This property returns valid information only during run time and only if the Player.URL property is also set.

See Also

  • Network Object
  • Player.URL


Network.recoveredPackets

The recoveredPackets property retrieves the number of recovered packets.

Syntax

player.network.recoveredPackets

Possible Values

This property is a read-only Number (long).

Remarks

Each time file playback is stopped and restarted, this property is set to zero. It is not reset if file playback is paused.

This property returns valid information only during run time and only if the Player.URL property is also set. It will equal zero when using the HTTP protocol, which is lossless.

See Also

  • Network Object
  • Player.URL


Network.setProxyBypassForLocal

The setProxyBypassForLocal method specifies a value indicating whether the proxy server is bypassed if the origin server is on a local network.

Syntax

player.network.setProxyBypassForLocal(protocol, bypass)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

bypass

Boolean specifying whether the proxy server is bypassed.

Return Values

This method does not return a value.

Remarks

This method has no effect unless getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object


Network.setProxyExceptionList

The setProxyExceptionList method specifies the proxy exception list.

Syntax

player.network.setProxyExceptionList(protocol, list)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

list

String specifying a comma-delimited list of hosts for which the proxy server is bypassed.

Return Values

This method does not return a value.

Remarks

This is a list of computers, domains, and/or addresses that will bypass the proxy server when the host portion of the target URL matches an entry in the list.

Wildcards can be used in the list entries via the ‘*’ character. For example, “*.com” would match all hosts in the “com” domain while “67.*” would match all hosts in the 67 class A subnet.

This method has no effect unless getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object


Network.setProxyName

The setProxyName method specifies the name of the proxy server to use.

Syntax

player.network.setProxyName(protocol, name)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

name

String specifying the name of the proxy server to use.

Return Values

This method does not return a value.

Remarks

This method has no effect unless getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object


Network.setProxyPort

The setProxyPort method specifies the proxy port to use.

Syntax

player.network.setProxyPort(protocol, port)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

port

Number (long) specifying the proxy port to use.

Return Values

This method does not return a value.

Remarks

This method has no effect unless getProxySettings returns a value of two (use manual settings).

See Also

  • Network Object


Network.setProxySettings

The setProxySettings method specifies the proxy setting for a given protocol.

Syntax

player.network.setProxySettings(protocol, setting)

Parameters

protocol

String specifying the protocol name. Contains one of the following values.

Value | Description
HTTP | Hypertext Transfer Protocol
MMS | Microsoft Media Services

setting

Number (long) containing one of the following values.

Value | Description
0 | Do not use a proxy server.
1 | Use the proxy settings of the current browser (only valid for HTTP).
2 | Use the manually specified proxy settings.
3 | Auto-detect the proxy settings.

Return Values

This method does not return a value.

See Also

  • Network Object


Network.sourceProtocol

The sourceProtocol property retrieves the source protocol used to receive data.

Syntax

player.network.sourceProtocol

Possible Values

This property is a read-only String containing one of the following values.

Value | Description
MMSU | User Datagram Protocol
MMST | Transmission Control Protocol
HTTP | Hypertext Transfer Protocol
File | Local file playback
Multicast | Multicasting
Unicast | Unicasting

See Also

  • Network Object


Player Object

The Player object is the root object for the Windows Media Player control. It supports the properties, methods, and events listed in the following tables.

The Player object supports the following properties. Properties marked with an asterisk (*) are not accessible to skins.

Property | Description
cdromCollection | Retrieves the CdromCollection object.
closedCaption | Retrieves the ClosedCaption object.
controls | Retrieves the Controls object.
currentMedia | Specifies or retrieves the current Media object.
currentPlaylist | Specifies or retrieves the current Playlist object.
enableContextMenu * | Specifies or retrieves a value indicating whether to enable the context menu, which appears when the right mouse button is clicked.
enabled * | Specifies or retrieves a value indicating whether the Windows Media Player control is enabled.
error | Retrieves the Error object.
fullScreen * | Specifies or retrieves a value indicating whether video content is played back in full-screen mode.
isOnline | Retrieves a Boolean value indicating whether the user is connected to a network.
mediaCollection | Retrieves the MediaCollection object.
network | Retrieves the Network object.
openState | Returns a value indicating the state of the content source.
playlistCollection | Retrieves the PlaylistCollection object.
playState | Retrieves a value indicating the state of the Windows Media Player operation.
settings | Retrieves the Settings object.
status | Retrieves a value indicating the current status of the Windows Media Player.
stretchToFit | Specifies or retrieves a value indicating whether video will stretch to fit size of the Windows Media Player control video display.
uiMode * | Specifies or retrieves a value indicating which controls are shown in the user interface when Windows Media Player is embedded in a Web page.
URL | Specifies or retrieves the name of the clip to play.
versionInfo | Returns a String value specifying the version of the Windows Media Player.

* Not accessible to skins.

The Player object supports the following methods.

Method | Description
close | Closes the Windows Media Player.
launchURL | Sends a URL to the user’s default browser to be rendered.

The Player object supports the following events.

Event | Description
buffering | Occurs when the Windows Media Player control begins or ends buffering.
currentItemChange | Occurs when Controls.currentItem changes.
currentPlaylistChange | Occurs when the current playlist changes.
disconnect | Reserved for future use.
error | Occurs when the Windows Media Player control has an error condition.
markerHit | Occurs when a marker is reached.
mediaChange | Occurs when a media item changes.
mediaCollectionChange | Occurs when the media collection changes.
modeChange | Occurs when a mode of the player is changed.
openStateChange | Occurs when the Windows Media Player control changes state.
playlistChange | Occurs when a playlist changes.
playStateChange | Occurs when the play state of the Windows Media Player control changes.
positionChange | Occurs when the current position of the movie has changed.
scriptCommand | Occurs when a synchronized command or URL is received.
statusChange | Occurs when the status property changes value.

When embedded in a Web page, the Player object can be accessed using the ID value specified in the OBJECT tag. Within a skin definition file, it is accessed using the player global attribute. For illustration purposes in the reference syntax sections, player will be used as the object ID.


Player.buffering event

The buffering event occurs when the Windows Media Player control begins or ends buffering.

Syntax

buffering(Start)

Parameters

Start

Boolean containing one of the following values.

Value | Description
true | Buffering has started.
false | Buffering has ended.

See Also

  • Player Object


Player.cdromCollection

The cdromCollection property retrieves the CdromCollection object.

Syntax

player.cdromCollection

Possible Values

This property is a read-only CdromCollection object.

See Also

  • Player Object
  • CdromCollection Object


Player.close

The close method closes Windows Media Player.

Syntax

player.close()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • Player Object


Player.closedCaption

The closedCaption property retrieves the ClosedCaption object.

Syntax

player.closedCaption

Possible Values

This property is a read-only ClosedCaption object.

See Also

  • Player Object
  • ClosedCaption Object


Player.controls

The controls property retrieves the Controls object.

Syntax

player.controls

Possible Values

This property is a read-only Controls object.

See Also

  • Player Object
  • Controls Object


Player.currentItemChange event

The currentItemChange event occurs when Controls.currentItem changes.

Syntax

currentItemChange()

Example Code

The following Jscript example demonstrates an event handler for the Player.currentItemChange event. The player object was created with ID = "Player".

<!-- Create an HTML text box to display the media name. -->
<INPUT TYPE="TEXT" NAME="MEDIA">

<!-- Create an event handler. -->
<SCRIPT LANGUAGE = "JScript"  FOR = Player EVENT = currentItemChange()>

   // Display the name of the new media item.
   MEDIA.value = Player.currentMedia.name;

</SCRIPT>

See Also

  • Player Object
  • Controls.currentItem


Player.currentMedia

The currentMedia property specifies or retrieves the current Media object.

Syntax

player.currentMedia

Possible Values

This property is a read/write Media object.

Remarks

If the Settings.autoStart property is true, file playback begins automatically whenever you set currentMedia.

Setting currentMedia is a synchronous operation; control is not returned to the application until after the file has completed the open process.

This property takes a Media object, which can be acquired in several ways, such as calling MediaCollection.item or Playlist.item. To load a Media item using a file name, set the URL property instead.

See Also

  • Player Object
  • Settings.autoStart
  • Media Object


Player.currentPlaylist

The currentPlaylist property specifies or retrieves the current Playlist object.

Syntax

player.currentPlaylist

Possible Values

This property is a read/write Playlist object.

See Also

  • Player Object
  • Playlist Object


Player.currentPlaylistChange event

The currentPlaylistChange event occurs when the current playlist changes.

Syntax

currentPlaylistChange(change)

Parameters

change

Number (long) indicating what type of change occurred to the playlist. See playlistChange for a table of possible values.

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object
  • Player.currentPlaylist
  • Player.playlistChange


Player.enableContextMenu

The enableContextMenu property specifies or retrieves a value indicating whether to enable the context menu, which appears when the right mouse button is clicked.

Syntax

player.enableContextMenu

Possible Values

This property is a read/write Boolean.

Value | Description
true | Default. Enable the context menu.
false | Do not enable the context menu.

See Also

  • Player Object


Player.enabled

The enabled property specifies or retrieves a value indicating whether the Windows Media Player control is enabled.

Syntax

player.enabled

Possible Values

This property is a read/write Boolean.

Value | Description
true | Default. The Windows Media Player control is enabled.
false | The Windows Media Player control is disabled.

See Also

  • Player Object


Player.error

The error property retrieves the Error object.

Syntax

player.error

Possible Values

This property is a read-only Error object.

See Also

  • Player Object
  • Error Object


Player.error event

The error event occurs when there is an error condition.

Syntax

error()

See Also

  • Player Object


Player.fullScreen

The fullScreen property specifies or retrieves a value indicating whether video content is played back in full-screen mode.

Syntax

player.fullScreen

Possible Values

This property is a read/write Boolean.

Value | Description
true | Video content is played back in full-screen mode.
false | Default. Video content is not played back in full-screen mode.

Example Code

The following example creates an HTML input button that uses Player.fullScreen to switch an embedded player object to full screen mode. The player object was created with ID = "Player".

<INPUT type = button
       value = "Full Screen"
       name = FSBUTTON
       onclick = "
               /* Check to be sure the player is playing. */
               if (Player.playState == 3)
                  Player.fullScreen = 'true';
               ">

Note: Always be sure to inform the user how to return from full screen mode.

See Also

  • Player Object


Player.isOnline

The isOnline property retrieves a Boolean value indicating whether the user is connected to a network.

Syntax

player.isOnline

Possible Values

This property is a read-only Boolean.

Value | Description
true | The user is connected to a network.
false | The user is not connected to a network.

See Also

  • Player Object


Player.launchURL

The launchURL method sends a URL to the user’s default browser to be rendered.

Syntax

player.launchURL(URL)

Parameters

  URL

String value representing the URL to launch.

Return Values

This method does not return a value.

See Also

  • Player Object
    •


Player.markerHit event

The markerHit event occurs when a marker is reached.

Syntax

markerHit(MarkerNum)

Parameters

MarkerNum

Number (long) indicating the number of the marker that was hit.

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object


Player.mediaChange event

The mediaChange event occurs when a media item changes.

Syntax

mediaChange(Item)

Parameters

Item

Media object representing the item that changed.

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object


Player.mediaCollection

The mediaCollection property retrieves the MediaCollection object.

Syntax

player.mediaCollection

Possible Values

This property is a read-only MediaCollection object.

See Also

  • Player Object
  • MediaCollection Object


Player.mediaCollectionChange event

The mediaCollectionChange event occurs when the media collection changes.

Syntax

mediaCollectionChange()

See Also

  • Player Object
  • Player.mediaCollection


Player.modeChange event

The modeChange event occurs when a mode of the player is changed.

Syntax

modeChange(ModeName, NewValue)

Parameters

ModeName

String indicating the mode that was changed. Contains one of the following values.

Value | Description
shuffle | Tracks are played in random order.
loop | The entire sequence of tracks is played repeatedly.

NewValue

Boolean indicating the new state of the specified mode.

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object
  • Settings.getMode
  • Settings.setMode


Player.network

The network property retrieves the Network object.

Syntax

player.network

Possible Values

This property is a read-only Network object.

See Also

  • Player Object
  • Network Object


Player.openState

The openState property retrieves a value indicating the state of the content source.

Syntax

player.openState

Possible Values

This property is a read only Number (long).

Value | State | Description
0 | Undefined | Windows Media Player is in an undefined state.
1 | PlaylistChanging | New playlist is about to be loaded.
2 | PlaylistLocating | Windows Media Player is attempting to locate the playlist. The playlist can be local (database or text file) or remote.
3 | PlaylistConnecting | Connecting to the playlist.
4 | PlaylistLoading | Playlist has been found and is now being retrieved.
5 | PlaylistOpening | Playlist has been retrieved and is now being parsed and loaded.
6 | PlaylistOpenNoMedia | Playlist is open.
7 | PlaylistChanged | A new playlist has been assigned to currentPlaylist.
8 | MediaChanging | New media is about to be loaded.
9 | MediaLocating | Windows Media Player is locating the media file. The file can be local or remote.
10 | MediaConnecting | Connecting to the server that holds the media.
11 | MediaLoading | Media has been located and is now being retrieved.
12 | MediaOpening | Media has been retrieved and is now being opened.
13 | MediaOpen | Media is now open.
14 | BeginCodecAcquisition | Starting codec acquisition.
15 | EndCodecAcquisition | Codec acquisition is complete.
16 | BeginLicenseAcquisition | Acquiring a license to play DRM protected content.
17 | EndLicenseAcquisition | License to play DRM protected content has been acquired.
18 | BeginIndividualization | Begin DRM Individualization.
19 | EndIndividualization | DRM individualization has been completed.
20 | MediaWaiting | Waiting for media.
21 | OpeningUnknownURL | Opening a URL with an unknown type.

See Also

  • Player Object


Player.openStateChange event

The openStateChange event occurs when the openState property changes value.

Syntax

openStateChange(NewState)

Parameters

NewState

Number (long) specifying the new open state. See openState for a table of values.

Remarks

The Windows Media Player can go through several open states while it attempts to open a network file, such as locating the server, connecting to the server, and finally opening the file. This event will be fired each time the open state changes.

The value of event parameters is specified by the 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.

See Also

  • Player Object
  • Player.openState


Player.playlistChange event

The playlistChange event occurs when a playlist changes.

Syntax

playlistChange(Playlist, change)

Parameters

Playlist

Playlist object which changed.

change

Number (long) indicating what type of change occurred to the playlist. Includes one of the following values.

Number | Name
0 | Unknown
1 | Clear
2 | InfoChange
3 | Move
4 | Delete
5 | Insert
6 | Append
7 | Private
8 | NameChange
9 | Morph

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object


Player.playlistCollection

The playlistCollection property retrieves the PlaylistCollection object.

Syntax

player.playlistCollection

Possible Values

This property is a read-only PlaylistCollection object.

See Also

  • Player Object
  • PlaylistCollection Object


Player.playState

The playState property retrieves a value indicating the state of the Windows Media Player operation.

Syntax

player.playState

Possible Values

This property is a read-only Number (long).

Value | State | Description
0 | Undefined | Windows Media Player is in an undefined state.
1 | Stopped | Playback of the current media clip is stopped.
2 | Paused | Playback of the current media clip is paused. When media is paused, resuming playback begins from the same location.
3 | Playing | The current media clip is playing.
4 | ScanForward | The current media clip is fast forwarding.
5 | ScanReverse | The current media clip is fast rewinding.
6 | Buffering | The current media clip is getting additional data from the server.
7 | Waiting | Connection is established, however the server is not sending bits. Waiting for session to begin.
8 | MediaEnded | Media has completed playback and is at its end.
9 | Transitioning | Preparing new media.
10 | Ready | Ready to begin playing.

Example Code

The following JScript code shows the use of the player.playState property. An HTML text element, named "myText", displays the current status. The player object was created with ID = "Player".

// Test if Windows Media Player is in the playing state.
if (3 == Player.playState)
  myText.value = "Windows Media Player is playing!";
else
  myText.value = "Windows Media Player is NOT playing!";

See Also

  • Player Object


Player.playStateChange event

The playStateChange event occurs when there is a change in the playState property.

Syntax

playStateChange(NewState)

Parameters

NewState

Long value which specifies the new playState. See playState for a table of possible values.

Remarks

The value of event parameters is specified by the 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.

Example Code

The following example demonstrates an event handler for the Player.playStateChange event. An HTML text element, named "myText", displays the new play state. The player object was created with ID = "Player".

<SCRIPT LANGUAGE = "JScript"  FOR = Player EVENT = playStateChange(NewState)>

// Test for the player current state, display a message for each.
switch (NewState){
  case 1:
   myText.value = "Stopped";
   break;

  case 2:
   myText.value = "Paused";
   break;

  case 3:
   myText.value = "Playing";
   break;

  // Other cases go here.

  default:
   myText.value = "";
}
</SCRIPT>

See Also

  • Player Object
  • Player.playState


Player.positionChange event

The positionChange event occurs when the current position of the media has changed.

Syntax

positionChange(oldPosition, newPosition)

Parameters

oldPosition

Number (double) specifying the old position.

newPosition

Number (double) specifying the new position.

Remarks

The value of event parameters is specified by the 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.

See Also

  • Player Object


Player.scriptCommand event

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

Syntax

scriptCommand(scType, Param)

Parameters

scType

String specifying the type of script command.

Param

String specifying the script command.

Remarks

Commands can be embedded among the sounds and images of an .asf file. 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 an ASF stream to be handled by the scriptCommand event.

One type of command is a URL (Uniform Resource Locator). URL-type commands received by the player control are invoked automatically in your default Internet browser if the invokeURLs property is set to true.

The player control always processes incoming URL-type commands in the following manner:

  1. A URL-type command is received.
  2. scriptCommand is called.
  3. After scriptCommand returns, invokeURLs is checked.
  4. If invokeURLs is true and the command is a URL-type, the specified URL is invoked. If invokeURLs is false or if the command is not a URL-type, the command is ignored.

When authoring an .asf 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 = http://myweb/mypage.html&&myframe

The other types of script commands automatically processed by the player control include FILENAME, TEXT, EVENT, and OPENEVENT.

  • For the FILENAME type, the Windows Media Player control resets its URL property, attempts to open the specified file, and begins playing the new stream immediately.
  • For the TEXT type command, the control displays the associated text in the captioning window of Windows Media Player.
  • The EVENT type tells the control to execute instructions defined for the specified event.
  • The OPENEVENT type command buffers the associated EVENT type command for timely execution of the EVENT script.

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 player control, they are still handed off to the scriptCommand event.

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 the 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.

See Also

  • Player Object
  • Player.URL
  • Settings.invokeURLs


Player.settings

The settings property retrieves the Settings object.

Syntax

player.settings

Possible Values

This property is a read-only Settings object.

See Also

  • Player Object
  • Settings Object


Player.status

The status property retrieves a value indicating the status of Windows Media Player.

Syntax

player.status

Possible Values

This property is a read-only String.

Remarks

The values contained in this property are subject to change at any time, and should be used for display purposes only.

The statusChange event is fired whenever this property changes value.

See Also

  • Player Object
  • Player.statusChange


Player.statusChange event

The statusChange event occurs when the status property changes value.

Syntax

statusChange()

See Also

  • Player Object
  • Player.status


Player.stretchToFit

The stretchToFit property specifies or retrieves a value indicating whether video displayed by the Windows Media Player control automatically sizes to fit the video window, when the video window is larger than the dimensions of the video image.

Syntax

player.stretchToFit

Possible Values

This property is a read/write Boolean.

Value | Description
true | The video will stretch to fit the window.
false | Default. The video will not stretch to fit the window.

Remarks

When stretchToFit is set to true, the Windows Media Player control maintains the original aspect ratio of the video. If the aspect ratio of the video does not match the aspect ratio of the video window, black mask areas may appear on either the top and the bottom, or left and right, of the video image.

This property applies to the Windows Media Player control only when embedded in a Web page.


Player.uiMode

The uiMode property specifies or retrieves a value indicating which controls are shown in the user interface when Windows Media Player is embedded in a Web page.

Syntax

player.uiMode

Possible Values

This property is a read/write String.

Value | Description | Audio example | Video example
none | Player is embedded without controls, and with only the video or visualization window displayed. | uiMode="none" with audio | uiMode="none" with video
mini | Player is embedded with the status window, play/pause, stop, mute, and volume controls shown in addition to the video or visualization window. | uiMode="mini" with audio | uiMode="mini" with video
full | Default. Player is embedded with the status window, seek bar, play/pause, stop, mute, next, previous, fast forward, fast reverse, and volume controls in addition to the video or visualization window. | uiMode="full" with audio | uiMode="full" with video

Remarks

This property specifies the appearance of the control panel portion of the embedded Windows Media Player. Regardless of this setting, a window is present for the display of video clips and audio visualizations. This window can be hidden in mini or full mode by specifying a height of 40 in the OBJECT tag, which is measured from the bottom, and leaves the controls portion of the user interface visible. If no embedded interface is desired, set both width and height to zero.

If the window is visible and audio content is being played, the visualization displayed will be the one most recently used in Windows Media Player.

See Also

  • Player Object


Player.URL

The URL property specifies or retrieves the name of the clip to play.

Syntax

player.URL

Possible Values

This property is a read/write String with no default value.

See Also

  • Player Object


Player.versionInfo

The versionInfo property retrieves a String value specifying the version of the Windows Media Player.

Syntax

player.versionInfo

Possible Values

This property is a read-only String in the following format: “7.0.0.XXXX” where XXXX represents the build number.

See Also

  • Player Object


Playlist Object

The Playlist object provides a way to organize media items in a list for easy manipulation using the following properties and methods.

The Playlist object supports the following properties.

Property | Description
attributeCount | Retrieves the number of attributes associated with the playlist.
attributeName | Retrieves the name of an attribute specified by an index.
count | Retrieves the number of items in the playlist.
name | Specifies or retrieves the name of the playlist.

The Playlist object supports the following methods.

Method | Description
appendItem | Adds a media item to the end of the playlist.
clear | Reserved for future use.
getItemInfo | Retrieves the value of a playlist attribute.
insertItem | Inserts a media item into the playlist at the specified location.
isIdentical | Retrieves a value indicating whether the supplied Playlist object is identical to the current one.
item | Retrieves the media item at the specified index.
moveItem | Changes the location of an item in the playlist.
removeItem | Removes the specified item from the playlist.
setItemInfo | Specifies the value of a playlist attribute.

The Playlist object is accessed through the following properties and methods.

Object | Property or method
Cdrom | playlist
MediaCollection | getAll, getByAlbum, getByAttribute, getByAuthor, getByGenre, getByName
Player | currentPlaylist
PlaylistArray | item
PlaylistCollection | newPlaylist

Because it is the most common means of access, player.currentPlaylist is used for purposes of illustration in the reference syntax sections.


Playlist.appendItem

The appendItem method adds a media item to the end of the playlist.

Syntax

player.currentPlaylist.appendItem(item)

Parameters

item

Media object to be added.

Return Values

This method does not return a value.

See Also

  • Playlist Object


Playlist.attributeCount

The attributeCount property retrieves the number of attributes associated with the playlist.

Syntax

player.currentPlaylist.attributeCount

Possible Values

This property is a read-only Number (long).

Remarks

Because playlists can come from many different sources, they can have several different sets of properties. This method retrieves the total number of properties available so that the other methods of the Playlist object can access them.

Example

The following sample is a JScript function that illustrates how various Playlist and Media properties and methods are used. The file that contains this function, and the skin definition file that displays the results, are included under ASX in the Samples directory that was installed with the SDK.

function onLoad() {
  var display;
  var pl = player.currentPlaylist;

  pl.setItemInfo("custom playlist attribute", "changed");
  pl.item(0).setItemInfo("new custom attribute", "5");

  display = pl.attributeCount + " Playlist Attributes:\r\r";

  for (var i = 0; i < pl.attributeCount; ++i) {
    display = display + pl.attributeName(i) + ": ";
    display = display + pl.getItemInfo(pl.attributeName(i)) + "\r";
  }

  for (var j = 0; j < pl.count; ++j) {
    display = display + "\rTrack " + j + "\r"
    display = display + pl.item(j).attributeCount + " Attributes:\r\r";

    for (var k = 0; k < pl.item(j).attributeCount; ++k) {
      var it = pl.item(j);  // Media object
      display = display + it.getAttributeName(k) + ": ";
      display = display + it.getItemInfo(it.getAttributeName(k)) + "\r";
    }
  }

  myText.value = display;
}

See Also

  • Playlist Object
  • Playlist.attributeName
  • Playlist.getItemInfo
  • Playlist.setItemInfo


Playlist.attributeName

The attributeName property retrieves the name of an attribute specified by an index.

Syntax

player.currentPlaylist.attributeName(index)

Parameters

index

Number (long) containing the index.

Possible Values

This property is a read-only String.

Remarks

The number of attributes is retrieved with the attributeCount property. Given an index, attributeName returns a String that can be used in conjunction with setItemInfo and getItemInfo to specify and retrieve the value for an attribute.

Example

Please see the attributeCount property for a sample illustrating the use of this property.

See Also

  • Playlist Object
  • Playlist.attributeCount
  • Playlist.getItemInfo
  • Playlist.setItemInfo


Playlist.count

The count property retrieves the number of media items in the playlist.

Syntax

player.currentPlaylist.count

Possible Values

This property is a read-only Number (long).

Example

Please see the attributeCount property for a sample illustrating the use of this property.

See Also

  • Playlist Object


Playlist.getItemInfo

The getItemInfo method retrieves the value of a playlist attribute.

Syntax

player.currentPlaylist.getItemInfo(name)

Parameters

name

String containing the name of the attribute to be retrieved.

Return Values

This method returns a String.

Example

Please see the attributeCount property for a sample illustrating the use of this property.

See Also

  • Playlist Object
  • Playlist.setItemInfo


Playlist.insertItem

The insertItem method inserts a media item into the playlist at the specified location.

Syntax

player.currentPlaylist.insertItem(index, item)

Parameters

index

Number (long) containing the index at which to add the item.

item

Media object to insert.

Return Values

This method does not return a value.

Remarks

All items after the inserted item will have their index numbers increased by one.

See Also

  • Playlist Object
  • Playlist.item
  • Playlist.removeItem


Playlist.isIdentical

The isIdentical method retrieves a value indicating whether the supplied Playlist object is identical to the current one.

Syntax

player.currentPlaylist.isIdentical(playlist)

Parameters

playlist

Playlist object to compare to the current one.

Return Values

This method returns a Boolean.

See Also

  • Playlist Object


Playlist.item

The item method retrieves the media item at the specified index.

Syntax

player.currentPlaylist.item(index)

Parameters

index

Number (long) containing the index.

Return Values

This method returns a Media object.

Example

Please see the attributeCount property for a sample illustrating the use of this property.

See Also

  • Playlist Object
  • Media Object
  • Playlist.insertItem
  • Playlist.removeItem


Playlist.moveItem

The moveItem method changes the location of an item in the playlist.

Syntax

player.currentPlaylist.moveItem(oldIndex, newIndex)

Parameters

oldIndex

Number (long) containing the old index.

newIndex

Number (long) containing the new index.

Return Values

This method does not return a value.

Remarks

Playlists stored in the database can change outside your control. Be sure to monitor and handle all Playlist events so that the order of items in the playlist does not change unexpectedly.

See Also

  • Playlist Object


Playlist.name

The name property specifies or retrieves the name of the playlist.

Syntax

player.currentPlaylist.name

Possible Values

This property is a read/write String.

See Also

  • Playlist Object


Playlist.removeItem

The removeItem method removes the specified item from the playlist.

Syntax

player.currentPlaylist.removeItem(item)

Parameters

item

Media object to be removed.

Return Values

This method does not return a value.

Remarks

If the item removed is the currently playing track (Player.currentMedia), playback stops and the next item in the playlist becomes the current one. If there is no next item, the previous item is used, or if there are no other items, then Player.currentMedia is set to NULL.

See Also

  • Playlist Object
  • Playlist.insertItem
  • Playlist.item
  • Player.currentMedia


Playlist.setItemInfo

The setItemInfo method specifies the value of a playlist attribute.

Syntax

player.currentPlaylist.setItemInfo(name, value)

Parameters

name

String containing the name of the attribute to be set.

value

String containing the new value for the attribute.

Return Values

This method does not return a value.

Example

Please see the attributeCount property for a sample illustrating the use of this property.

See Also

  • Playlist Object
  • Playlist.getItemInfo


PlaylistArray Object

The PlaylistArray object provides a way to access playlists by index number.

The PlaylistArray object supports the following property.

Property | Description
count | Retrieves the number of playlists in the playlist array.

The PlaylistArray object supports the following method.

Method | Description
item | Retrieves the Playlist object at the given index.

The PlaylistArray object is accessed through the following methods.

Object | Method
PlaylistCollection | getAll, getByName

For purposes of illustration, player.playlistCollection.getAll() is used in the reference syntax sections.


PlaylistArray.count

The count property retrieves the number of playlists in the playlist array.

Syntax

player.playlistCollection.getAll().count

Possible Values

This property is a read-only Number (long).

See Also

  • PlaylistArray Object


PlaylistArray.item

The item method retrieves the playlist at the given index.

Syntax

player.playlistCollection.getAll().item(index)

Parameters

index

Number (long) containing the index of the playlist to be retrieved.

Return Values

This method returns a Playlist object.

See Also

  • PlaylistArray Object


PlaylistCollection Object

The PlaylistCollection object provides a way to organize your playlists.

The PlaylistCollection object supports the following methods.

Method | Description
getAll | Retrieves a PlaylistArray object containing all the playlists in the media library.
getByName | Retrieves a PlaylistArray object containing the specified playlist, if it exists.
importPlaylist | Adds a playlist to the PlaylistCollection.
isDeleted | Retrieves a value indicating whether the specified playlist is in the deleted items folder.
newPlaylist | Creates a new playlist.
remove | Removes a playlist from the PlaylistCollection.
setDeleted | Moves a playlist to the deleted items folder.

The PlaylistCollection object is accessed through the following property.

Object Property


PlaylistCollection.getAll

The getAll method retrieves a PlaylistArray object containing all the playlists in the media library.

Syntax

player.playlistCollection.getAll()

Parameters

This method takes no parameters.

Return Values

This method returns a PlaylistArray object.

See Also

  • PlaylistCollection Object
  • PlaylistArray Object


PlaylistCollection.getByName

The getByName method retrieves a PlaylistArray object containing the specified playlist, if it exists.

Syntax

player.playlistCollection.getByName(name)

Parameters

name

String containing the name of the playlist to be retrieved.

Return Values

This method returns a PlaylistArray object.

Remarks

Playlists are uniquely named within the database, so this method is guaranteed to return a PlaylistArray object containing no more than one playlist. Use PlaylistArray.count to determine whether the playlist exists. If count is zero, the playlist does not exist.

See Also

  • PlaylistCollection Object
  • PlaylistArray Object
  • PlaylistArray.count


PlaylistCollection.importPlaylist

The importPlaylist method adds a playlist to the PlaylistCollection.

Syntax

player.playlistCollection.importPlaylist(playlist)

Parameters

playlist

Playlist object to be added.

Return Values

This method does not return a value.

See Also

  • PlaylistCollection Object
  • PlaylistCollection.newPlaylist
  • PlaylistCollection.remove


PlaylistCollection.isDeleted

The isDeleted method retrieves a value indicating whether the specified playlist is in the deleted items folder.

Syntax

player.playlistCollection.isDeleted(playlist)

Parameters

playlist

The Playlist object to be searched for.

Return Values

This method returns a Boolean.

See Also

  • PlaylistCollection Object


PlaylistCollection.newPlaylist

The newPlaylist method creates a new playlist.

Syntax

player.playlistCollection.newPlaylist(name)

Parameters

name

String containing the name of the playlist to be created.

Return Values

This method returns a Playlist object.

Remarks

If the playlist name specified is not unique in the database, an error will result. Use getByName and PlaylistArray.count to determine whether a playlist already exists in the database.

See Also

  • PlaylistCollection Object
  • PlaylistCollection.getByName
  • PlaylistArray.count
  • PlaylistCollection.importPlaylist
  • PlaylistCollection.remove


PlaylistCollection.remove

The remove method removes a playlist from the PlaylistCollection.

Syntax

player.playlistCollection.remove(playlist)

Parameters

playlist

The Playlist object to be removed.

Return Values

This method does not return a value.

See Also

  • PlaylistCollection Object
  • PlaylistCollection.importPlaylist
  • PlaylistCollection.newPlaylist


PlaylistCollection.setDeleted

The setDeleted method moves a playlist to the deleted items folder.

Syntax

player.playlistCollection.setDeleted(playlist)

Parameters

playlist

The Playlist object to be moved.

Return Values

This method returns a Boolean indicating whether the playlist was successfully moved.

See Also

  • PlaylistCollection Object


Settings Object

The Settings object provides a way to modify various Media Player settings using the following properties and methods.

The Settings object supports the following properties.

Property | Description
autoStart | Specifies or retrieves a value indicating whether the current media item begins playing automatically.
balance | Specifies or retrieves the current stereo balance.
baseURL | Specifies or retrieves the base URL used for relative path resolution.
defaultFrame | Specifies or retrieves the name of the frame used to display a URL received in a scriptCommand.
enableErrorDialogs | Specifies or retrieves a value indicating whether error dialogs are shown automatically.
invokeURLs | Specifies or retrieves a value indicating whether URL events should launch a Web browser.
mute | Specifies or retrieves a value indicating whether audio is muted.
playCount | Specifies or retrieves the number of times a media item will play.
rate | Specifies or retrieves the current playback rate.
volume | Specifies or retrieves the current volume.

The Settings object supports the following methods.

Method | Description
getMode | Determines whether the loop mode or shuffle mode is active.
isAvailable | Determines whether a specified type of information is available or a given action can be performed.
setMode | Sets the loop mode or shuffle mode to active or inactive.

The Settings object is accessed through the following property.

Object Property


Settings.autoStart

The autoStart property specifies or retrieves a value indicating whether the current media item begins playing automatically.

Syntax

player.settings.autoStart

Possible Values

This property is a read/write Boolean.

Value | Description
true | Default. The media item begins playing automatically.
false | The media item does not begin playing automatically.

Remarks

If autoStart is set to true, the media clip will begin playing as soon as Player.URL or Player.currentMedia is set. Otherwise, it will not start playing until the player.controls.play method is called.

Because the autoStart property can be set globally by external events (such as loading a CD), you should set autoStart to false immediately before you set Player.URL or Player.currentMedia if you wish to ensure that the media item does not start playing immediately.

See Also

  • Settings Object
  • Player.URL
  • Player.currentMedia


Settings.balance

The balance property specifies or retrieves the current stereo balance.

Syntax

player.settings.balance

Possible Values

This property is a read/write Number (long) ranging from –100 to 100 with a default value of zero.

Remarks

The default value zero indicates that the sound is balanced equally between the left and right speakers. A value of –100 indicates that all sound is going to the left speaker, while a value of 100 indicates that all sound is going to the right speaker.

See Also

  • Settings Object


Settings.baseURL

The baseURL property specifies or retrieves the base URL used for relative path resolution.

Syntax

player.settings.baseURL

Possible Values

This property is a read/write String.

Remarks

This property specifies the base HTTP URL that is passed as the command parameter by the scriptCommand event. The base URL is concatenated with the relative URL as follows:

  1. A trailing forward slash (/) is added to the value of the baseURL property.
  2. A leading period, backward slash, or forward slash (., \, and /) are deleted from the relative URL.
  3. The relative URL is added to the end of the base URL.
  4. All slashes in the resulting fully qualified URL are pointed in the same direction (converted to forward or backward slashes) based on the direction of the first slash character encountered in the new URL.

Note   The player control does not support the use of two periods (..) in the relative URL to indicate the parent of the current location.

See Also

  • Settings Object
  • Player.scriptCommand


Settings.defaultFrame

The defaultFrame property specifies or retrieves the name of the frame used to display a URL received in a scriptCommand.

Syntax

player.settings.defaultFrame

Possible Values

This property is a read/write String corresponding to the value of the name attribute of the target FRAME element.

Remarks

If a target frame is specified in the scriptCommand event itself, this property is ignored.

See Also

  • Settings Object
  • Player.scriptCommand


Settings.enableErrorDialogs

The enableErrorDialogs property specifies or retrieves a value indicating whether error dialogs are shown automatically.

Syntax

player.settings.enableErrorDialogs

Possible Values

This property is a read/write Boolean.

Value | Description
true | Default. Error dialogs are shown automatically.
false | Error dialogs are not shown automatically.

See Also

  • Settings Object


Settings.getMode

The getMode method determines whether the loop mode or shuffle mode is active.

Syntax

player.settings.getMode(modeName)

Parameters

modeName

String specifying the name of the mode in question, containing one of the following values.

String | Description
loop | Mode indicating that the sequence of tracks repeats itself.
shuffle | Mode indicating that the tracks are played in random order.

Return Values

This method returns a Boolean value indicating whether the specified mode is active.

See Also

  • Settings Object
  • Settings.setMode


Settings.invokeURLs

The invokeURLs property specifies or retrieves a value indicating whether URL events should launch a Web browser.

Syntax

player.settings.invokeURLs

Possible Values

This property is a read/write Boolean.

Value | Description
true | Default. URL events should launch a browser.
false | URL events should not launch a browser.

Remarks

Media files can contain Uniform Resource Locators (URLs). When a URL is sent to the Windows Media Player control, it is passed first to the scriptCommand event handler regardless of the value in invokeURLs. After scriptCommand exits, Windows Media Player checks invokeURLs to determine whether to launch the default Internet browser with the URL. You can selectively display URLs by checking them in scriptCommand and setting invokeURLs as desired.

See Also

  • Settings Object
  • Player.scriptCommand


Settings.isAvailable

The isAvailable method determines whether a specified type of information is available or a given action can be performed.

Syntax

player.settings.isAvailable(name)

Parameters

name

String containing one of the following values.

String | Description
Rate | Determines whether the rate property can be set.

Return Values

This method returns a Boolean value.

See Also

  • Settings Object


Settings.mute

The mute property specifies and retrieves a value indicating whether audio is muted.

Syntax

player.settings.mute

Possible Values

This property is a read/write Boolean.

Value | Description
true | Audio is muted.
false | Default. Audio is not muted.

See Also

  • Settings Object


Settings.playCount

The playCount property specifies or retrieves the number of times a media item will play.

Syntax

player.settings.playCount

Possible Values

This property is a read/write Number (long) with a minimum value of one and a default value of one.

See Also

  • Settings Object


Settings.rate

The rate property specifies or retrieves the current playback rate.

Syntax

player.settings.rate

Possible Values

This property is a read/write Number (double) with a default value of 1.0.

Remarks

This property only applies to video media.

This property acts as a multiplier value that allows you to play the clip at a faster or slower rate. The default value of 1.0 indicates the authored speed. Note that the audio track becomes difficult to understand at rates lower than 0.5 or higher than 1.5. A playback rate of 2 equates to twice the normal playback speed.

Other considerations apply as well, depending on media type:

  • Advanced streaming format (ASF or WMV): Optimal values for this property are from 1 to 10, or from –1 to –10 for reverse play. Values with an absolute magnitude greater than 10 are allowed, but not very meaningful. Audio plays only when the value is 1.
  • Other Media Types: This property can range from 0 to 9. Negative values are not allowed. Values less than 1 represent slow motion. Values above 9 are allowed, but are not very meaningful.

The Controls.fastForward method changes the value of rate to 5.0, while the Controls.fastReverse method changes rate to –5.0.

See Also

  • Settings Object
  • Controls.fastForward
  • Controls.fastReverse


Settings.setMode

The setMode method sets the loop mode or shuffle mode to active or inactive.

Syntax

player.settings.setMode(modeName, state)

Parameters

modeName

String specifying the name of the mode being changed, containing one of the following values.

String | Description
loop | Mode indicating whether the sequence of tracks repeats itself.
shuffle | Mode indicating whether the tracks are played in random order.

state

Boolean specifying the new state of the specified mode.

Return Values

This method does not return a value.

See Also

  • Settings Object
  • Settings.getMode


Settings.volume

The volume property specifies or retrieves the current volume.

Syntax

player.settings.volume

Possible Values

This property is a read/write Number (long) ranging from 0 to 100.

Remarks

Zero specifies no volume and 100 specifies full volume. If no value is specified for this property, it defaults to the last volume setting established for the player.

See Also

  • Settings Object


StringCollection Object

The StringCollection object provides a way to manipulate a collection of strings.

The StringCollection object supports the following property.

Property | Description
count | Retrieves the number of items in the string collection.

The StringCollection object supports the following method.

Method | Description
item | Retrieves the string at the given index.

The StringCollection object is accessed through the following method.

Object | Method
MediaCollection | getAttributeStringCollection

For purposes of illustration, player.mediaCollection.getAttributeStringCollection(attribute, mediaType) is used in the reference syntax sections.


StringCollection.count

The count property retrieves the number of items in the string collection.

Syntax

player.mediaCollection.getAttributeStringCollection(attribute, mediaType).count

Possible Values

This property is a read-only Number (long).

See Also

  • StringCollection Object


StringCollection.item

The item method retrieves the string at the given index.

Syntax

player.mediaCollection.getAttributeStringCollection(attribute, mediaType).item(index)

Parameters

index

Number (long) containing the index.

Return Values

This method returns a String.

Remarks

The StringCollection object is used to retrieve the set of values available for an attribute. For example, the MediaCollection.getAttributeStringCollection method can be used to retrieve a StringCollection object representing all the values for the Genre attribute within the Audio media type. The item property can then be used to iterate through all of the possible values for the Genre attribute.

See Also

  • StringCollection Object
  • MediaCollection.getAttributeStringCollection


Windows Media Player Version 6.4 Plug-in for Netscape Navigator

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player plug-in for Netscape Navigator is designed to support the Windows Media Player multimedia experience for users of Netscape Navigator. The following sections explain what the Windows Media Player plug-in can do, and how you can use it in your applications.

Section | Description
About the Windows Media Player Plug-in for Netscape Navigator | Discusses the plug-in, and its operational and programmable features.
Using the Windows Media Player Plug-in for Netscape Navigator | Discusses how to enable the plug-in in a Hypertext Markup Language (HTML) page, and the differences in scripting between Netscape Navigator and Microsoft Internet Explorer.
Windows Media Player Plugin for Netscape Navigator Reference | Discusses the methods, properties, and events that are supported by the plug-in for Netscape Navigator.


About the Windows Media Player Plug-in for Netscape Navigator

This topic applies to Windows Media Player version 6.4 only.

Because Netscape Navigator cannot communicate directly with Microsoft® ActiveX® controls, Windows Media Player includes a plug-in (Npdsplay.dll) to allow users of Netscape Navigator to watch Windows Media content. With the help of a proxy applet (Npds.zip), events triggered by the plug-in are visible in Netscape Navigator, and thus can be scripted. The two-way interactions between the browser and the ActiveX control take place through the following steps:

  • The browser communicates with the applet
  • The applet coordinates with the plug-in
  • The plug-in interacts with the ActiveX control

The applet is required to handle events. When no events are handled in the script, Netscape Navigator communicates with Windows Media Player only through the plug-in, bypassing the proxy applet:

  • The browser interacts with the plug-in
  • The plug-in interacts with the ActiveX control

The Windows Media Player plug-in for Netscape Navigator is fully scriptable. You can use it to develop embedded applications in Netscape Navigator that:

  • Invoke the methods of the Windows Media Player control.
  • Get and set the properties of the Windows Media Player control.
  • Receive events from the Windows Media Player control.

The Windows Media Player plug-in makes available to Netscape Navigator all the features of the ActiveX control, including control protocols, playlists, codecs, and event handling. It can render multimedia content in various formats, including:

  • Windows Media Format (ASF, WMA, WMV)
  • Windows Media Metafile (ASX)
  • Windows Media Audio (WMA)
  • Windows Media Audio Redirector (WAX)
  • Sound File (SND)
  • Waveform Audio (WAV)
  • Audio Interchange File Format (AIFF)
  • Moving Picture Experts Group standard one and two (MPEG-1 and MPEG-2)
  • MPEG Audio Layer III (MP3)
  • Musical Instrument Digital Interface (MIDI)
  • UNIX audio (AU)
  • QuickTime (MOV)

For more information about supported content formats, see Content Formats.


Using the Windows Media Player Plug-in for Netscape Navigator

This topic applies to Windows Media Player version 6.4 only.

To use the Windows Media Player plug-in, you must make sure that the Npdsplay.dll and Npds.zip files are installed in the Communicator\Program\Plugins directory within the installation directory of Netscape Navigator. Usually, these files are automatically installed when you run the Windows Media Player setup program. However, if Windows Media Player is installed before Netscape Navigator, these two files can sometimes be improperly installed in the Netscape Navigator Plugins directory. In this case, you must either reinstall Windows Media Player, or copy the two files into the Communicator\Program\Plugins directory. You can check whether the plug-in is properly installed by clicking About Plug-ins on the Help menu in Netscape Navigator, and looking for "Windows Media Player Plug-in Dynamic Link Library."

Using Windows Media Player with Netscape Navigator requires different scripting than that used with Microsoft® Internet Explorer. The following articles explain how to use the plug-in.

  • Embedding the Windows Media Player
  • Invoking Methods
  • Accessing Properties
  • Handling Events
  • Plug-in Samples


Embedding Windows Media Player

This topic applies to Windows Media Player version 6.4 only.

To accommodate cross-browser compatibility, you can enable Windows Media Player in a Web page so that it can be successfully downloaded to either Microsoft® Internet Explorer or Netscape Navigator. For Netscape Navigator, use the EMBED tag to embed a plug-in. For Internet Explorer, use the OBJECT tag to embed the Microsoft® ActiveX® control. To ensure that Windows Media Player is enabled properly for both types of browsers, you can nest the EMBED tags within the OBJECT tags, as illustrated in the following code segment.

<OBJECT ID="MediaPlayer" WIDTH=320 HEIGHT=240
    CLASSID="CLSID:22D6F312-B0F6-11D0-94AB-0080C74C7E95"
    STANDBY="Loading Windows Media Player components..."
    TYPE="application/x-oleobject">

  <PARAM NAME="FileName" VALUE="demo.asf">
  <EMBED TYPE="application/x-mplayer2"
    SRC="C:\Program Files\Windows Media Components\SDK\Samples\Plugin\demo.asf"
    NAME="MediaPlayer"
    WIDTH=320
    HEIGHT=240>
  </EMBED>
</OBJECT>

In this example, Windows Media Player is configured to play the demo.asf file in the C:\Program Files\Windows Media Components\SDK\Samples\Plugin directory. The Windows Media Player control is identified as MediaPlayer, which is specified by the ID attribute of the OBJECT tag. The plug-in is also named MediaPlayer, which is specified by the NAME attribute of the EMBED tag. You can use the object identifier MediaPlayer, in the script to refer to the Windows Media Player when invoking methods, accessing properties, and handling events.

The preceding code example uses branded MIME types to load Windows Media Player to play a Windows Media file. This use of branded MIME types ensures automatic version upgrade for the plug-in on a user machine. All other supported media types can be specified in a similar fashion. The following code snippet loads and, if necessary, upgrades the plug-in, and plays a WAV file, an AVI file, and an MP3 file.

<EMBED TYPE="application/x-mplayer2" SRC="myWAV.wav"></EMBED>
<EMBED TYPE="application/x-mplayer2" SRC="myAVI.avi"></EMBED>
<EMBED TYPE="application/x-mplayer2" SRC="myMP3.mp3"></EMBED>


Invoking Methods

This topic applies to Windows Media Player version 6.4 only.

Follow the usual object model to invoke a method through the Microsoft® Windows Media™ Player plug-in for Netscape Navigator. The following example defines forward and rewind buttons that invoke the FastForward and FastReverse methods of Windows Media Player.

<FORM>
    <INPUT TYPE=BUTTON
        NAME="ForwardButton"
        VALUE="Forward"
        ONCLICK="MediaPlayer.FastForward()">
    <INPUT TYPE=BUTTON
        NAME="ReverseButton"
        VALUE="Rewind"
        ONCLICK="MediaPlayer.FastRewind()">
</FORM>

This syntax for invoking methods works for both Netscape Navigator and Microsoft® Internet Explorer.


Accessing Properties

This topic applies to Windows Media Player version 6.4 only.

Accessing and modifying the properties of the Windows Media Player control requires somewhat different scripting syntax for Netscape Navigator and Microsoft® Internet Explorer. For example, to retrieve and set the FileName property from Netscape Navigator, use the following:

MediaPlayer.SetFileName("demo.asf");
var myTitle = MediaPlayer.GetFileName();

The corresponding statements in Internet Explorer are as follows:

MediaPlayer.FileName = "demo.asf"
var myTitle = MediaPlayer.FileName

To write a script that works under both browsers, check the browser type before accessing the properties. The following code segment shows how to toggle the mute setting for either Netscape Navigator or Internet Explorer.

function mute() {
    if (navigator.appName=="Netscape") {
        if (document.MediaPlayer.GetMute()=="0") {
            document.MediaPlayer.SetMute(1);
        } else if (document.MediaPlayerGetMute()=="1") {
            document.MediaPlayer.SetMute(0);
        }
    } else {
        if (document.MediaPlayer.Mute==0) {
            document.MediaPlayer.Mute = 1;
        } else if (document.MediaPlayer.Mute==1) {
            document.MediaPlayer.Mute = 0;
        }
    }
}


Handling Events in Netscape Navigator

This topic applies to Windows Media Player version 6.4 only.

Netscape Navigator employs a different event-handling mechanism from that of Microsoft® Internet Explorer. While Internet Explorer communicates with the Windows Media Player control directly to handle events dispatched to and from the control, Netscape Navigator requires a proxy applet to send events to and from the plug-in. Additional coding is therefore required to load the applet into an HTML page, using the APPLET tag. The required proxy applet for the Windows Media Player plug-in is packaged in the Npds.zip file that contains the npDSEvtObsProxy class. You can download the applet class as follows:

<APPLET MYSCRIPT code=NPDS.npDSEvtObsProxy.Class
        width=5 height=5 name=appObs>
</APPLET>

An instance of the applet class must be created immediately after the HTML page is loaded. After the applet is loaded in the HTML page, you must register the events you require before they can be dispatched to the associated event handlers. In the examples that follow, appObs refers to this proxy applet object.

To use events in Netscape Navigator with the Windows Media Player control, you must do the following:

  • Register the Events
  • Add Event Handlers

Register the Events

Before an event occurs, an event observer must be enabled to trap the event. The following code segment illustrates how to enable event observers.

var plugin = MediaPlayer;
appObs.setByProxyDSScriptCommandObserver(plugin, true);
appObs.setByProxyDSPlayStateChangeObserver(plugin, true);
appObs.setByProxyDSReadyStateChangeObserver(plugin, true);

This code registers three Windows Media Player control events: ScriptCommand, PlayStateChange, and ReadyStateChange. Each has its own observer. You must have event observers registered in a call to RegisterEventObservers when the page is loaded. To accomplish this, assign RegisterEventObservers() to the ONLOAD attribute of the BODY tag:

<BODY ONLOAD="RegisterEventObservers()">

Then implement the RegisterEventObservers function in the script as follows:

function RegisterEventObservers() {
    // This helper function is required to register event
    // observers with the Java proxy. Registration MUST be
    // done before desired events will be sent.
    var plugin = document.MediaPlayer;

    // Here are event observers to be activated in the plug-in.
    appObs.setByProxyDSScriptCommandObserver(plugin, true);
    appObs.setByProxyDSPlayStateChangeObserver(plugin, true);
    appObs.setByProxyDSReadyStateChangeObserver(plugin, true);

    // You can activate other event observers similarly.

}

This code ensures that all event observers are initialized before Windows Media Player is started. It also prevents the user from having to take action to enable an event.

Add Event Handlers

Each registered event observer requires a corresponding event handler. For information about other events and their associated parameters, see Windows Media Player Events.

In Microsoft® JScript® for Netscape Navigator, use the following syntax to declare an event handler, where EventName is the name of the Windows Media Player event:

function OnDSEventNameEvt (parameter1 [, parameter2... ] )
{
      // code goes here...
}

For the three events registered above, you would declare the event handlers as follows:

function OnDSScriptCommandEvt (scType, scParam)
{
      // code goes here...
}

function OnDSPlayStateChangeEvt (OldPlayState, NewPlayState)
{
    // code goes here...
}

function OnDSReadyStateChangeEvt (ReadyState)
{
      // code goes from here...
}


Plug-in Samples

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player plug-in samples show how to embed the Windows Media Player control in a Web page so that the scripted page will work in browsers that support embedding, for example, Netscape Navigator and Microsoft® Internet Explorer.

Scripting for Netscape Navigator differs somewhat from that for Internet Explorer. Browser compatibility can be an issue if you want your Web pages to be rendered in both browsers. There are differences in how Windows Media Player can be embedded in an HTML page, and in how events are handled and properties of the control are set and retrieved.

Five samples are provided to demonstrate how to use the Windows Media Player plug-in.

These samples are available in the Samples directory that was installed with the SDK. Find and open the readme.htm file to navigate through the samples.

The following table describes the plug-in samples.

Sample | Description
Sample1 | This simple HTML application shows how to embed the plug-in in an HTML page so that the page works in Netscape Navigator, Internet Explorer, and other browsers that support embedding.
Sample2 | This HTML application shows how to use properties and methods exposed by the plug-in.
Sample3 | This sample application shows how to handle events with basic scripting for multiple browsers. It demonstrates event handling in the form of alert boxes that appear whenever the state of the Windows Media Player control changes, or a script command is received from the media stream. These script commands are text strings that contain a transcript of the audio portion of the stream.
Sample4 | This sample shows more advanced scripting for event handling. Its behavior is the same as Sample3, but the HTML script uses external Microsoft® JScript® proxy files (.js) as containers for the scripting necessary to receive and handle the events and methods.
Sample5 | This sample is similar to Sample4 but adds Microsoft® Visual Basic® Scripting Edition (VBScript) to handle Internet Explorer events on the same page.


Windows Media Player Plugin for Netscape Navigator Reference

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player Plugin for Netscape Navigator supports all the methods, properties, and events in Windows Media Player version 6.4, except the following.

Properties

  • ChannelDescription
  • ChannelName
  • ChannelURL
  • DisplayMode
  • SAMILang
  • SAMIStyle

Event

  • Disconnect


Windows Media Player 7 for Mac Object Model

The following methods, properties, and events are currently supported for use with Microsoft® Windows Media™ Player 7 for Mac using the Netscape Navigator plug-in. The Netscape Navigator plug-in uses the Windows Media Player version 6.4 object model, and Windows Media Player 7 for Mac supports a subset of that functionality.

For further details about individual methods, properties, and events, see the Windows Media Player 6.4 Software Development Kit (SDK), or click the links in the following tables.

Windows Media Player 7 for Mac supports the following methods.

Method | Description
AboutBox | Displays version and copyright information about the Windows Media Player control.
Cancel | Cancels the Open method before the file completes opening.
GetCodecDescription | Retrieves the descriptive name of the given codec.
GetCodecInstalled | Retrieves a value indicating whether a given codec is installed.
GetCurrentEntry | Retrieves the current clip being played by the Windows Media Player control.
GetMarkerName | Retrieves the name of a marker, given its marker number.
GetMarkerTime | Retrieves a value indicating the presentation time of a given marker.
GetMediaInfoString | Retrieves show or clip information.
Next | Jumps to the next clip in a playlist.
Open | Opens a specified clip asynchronously.
Pause | Suspends playback at the current position in the clip.
Play | Starts playing a clip from the starting position or continues playing a paused or stopped clip.
Previous | Jumps to the previous clip in a playlist.
Stop | Stops playback of the current clip.

The Windows Media Player 7 for Mac supports the following properties. For unsupported properties, the Windows Media Player Version 6.4 object model default value is also the Macintosh default value.

Property | Description
AutoStart | Specifies or retrieves a value indicating whether to start playing the clip automatically.
Bandwidth | Retrieves the bandwidth of the current clip in bits per second (bps).
BaseURL | Retrieves a value indicating the base URL.
BufferingCount | Retrieves the number of times buffering occurred during playback of a clip.
BufferingProgress | Retrieves the percentage of buffering completed.
BufferingTime | Retrieves the buffering time in seconds.
CanSeek | Retrieves a value indicating whether the current file has the ability to seek to a specific time.
CanSeekToMarkers | Retrieves a value indicating whether markers in the file can be located with a seek operation.
ChannelDescription | Retrieves the station description.
ChannelName | Retrieves the station name.
ChannelURL | Retrieves the URL of the station metafile.
ClientID | Retrieves the unique ID of a client.
ConnectionSpeed | Retrieves the bandwidth selected during setup.
ContactAddress | Retrieves the station's contact address.
ContactEmail | Retrieves the station's e-mail address.
ContactPhone | Retrieves the station's contact telephone number.
CurrentMarker | Specifies or retrieves the current marker number.
CurrentPosition | Specifies or retrieves the clip's current position, in seconds.
DefaultFrame | Specifies or retrieves a value representing the default target HTTP frame.
Duration | Retrieves the length of the clip, in seconds.
EntryCount | Retrieves the number of entries contained in the current Windows Media metafile.
ErrorCode | Retrieves the current error code.
ErrorDescription | Retrieves a description of the current error state.
FileName | Specifies or retrieves the name of the clip to play.
HasError | Retrieves a value indicating whether the Windows Media Player control currently has an error.
HasMultipleItems | Retrieves a value indicating whether the current clip contains multiple items (playlists).
ImageSourceHeight | Retrieves the original image height of the current clip, in pixels.
ImageSourceWidth | Retrieves the original image width of the current clip, in pixels.
InvokeURLs | Specifies or retrieves a value indicating whether the Windows Media Player control automatically invokes URLs in a browser (URL flipping).
IsBroadcast | Retrieves a value indicating whether the source is a broadcast.
IsDurationValid | Retrieves a value indicating whether the value of the Duration property is valid.
LostPackets | Retrieves the number of packets lost during transmission of the stream.
MarkerCount | Retrieves the number of markers in the current clip.
Mute | Specifies or retrieves the current mute state of the Windows Media Player control.
OpenState | Retrieves the state of the content source.
PlayCount | Specifies or retrieves the number of times a clip plays.
PlayState | Retrieves a value indicating the state of the Windows Media Player operation.
PreviewMode | Specifies or retrieves a value indicating whether Windows Media Player is in preview mode.
ReadyState | Retrieves the state of readiness of the Windows Media Player control.
ReceivedPackets | Retrieves the number of packets received.
ReceptionQuality | Retrieves the accumulative percentage of packets received in the last 30 seconds.
RecoveredPackets | Retrieves the number of packets recovered.
SAMIFileName | Specifies or retrieves the name of the file that contains the closed captioning information.
SAMILang | Retrieves a value indicating the language displayed for closed captioning. Specifying this value is not supported.
SAMIStyle | Retrieves a value representing the closed captioning style. Specifying this value is not supported.
SelectionEnd | Specifies or retrieves the time within the current clip at which playback will stop.
SelectionStart | Specifies or retrieves the time within the current clip at which playback will begin.
SendErrorEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends error events.
SendKeyboardEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends keyboard events.
SendMouseClickEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends mouse click events.
SendMouseMoveEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends mouse move events.
SendOpenStateChangeEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends open state change events.
SendPlayStateChangeEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends play state change events.
SendWarningEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends warning events.
ShowAudioControls | Specifies or retrieves a value indicating whether the audio controls appear on the control bar.
ShowCaptioning | Specifies or retrieves a value indicating whether the closed caption area is visible and closed captioning is enabled.
ShowControls | Specifies or retrieves a value indicating whether the control bar is visible.
ShowDisplay | Specifies or retrieves a value indicating whether the display panel is visible.
ShowGotoBar | Specifies or retrieves a value indicating whether the Go To bar is visible.
ShowPositionControls | Specifies or retrieves a value indicating whether the position controls appear on the control bar.
ShowStatusBar | Specifies or retrieves a value indicating whether the status bar is visible.
ShowTracker | Specifies or retrieves a value indicating whether the trackbar is visible.
SourceLink | Retrieves the path to the current clip.
Volume | Specifies or retrieves the volume, in hundredths of decibels.

The Windows Media Player 7 for Mac supports the following events.

Event | Description
Buffering | Occurs when the Windows Media Player control begins or ends buffering.
Click | Occurs when a user clicks the mouse with the pointer over the Windows Media Player control.
DblClick | Occurs when a user double-clicks the mouse with the pointer over the Windows Media Player control.
EndOfStream | Occurs when the end of the clip is reached.
Error | Occurs when the Windows Media Player control has an error condition.
KeyDown | Occurs when a key is pressed.
KeyPress | Occurs when a key is pressed and released.
KeyUp | Occurs when a key is released.
MarkerHit | Occurs when a marker is reached.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved.
MouseUp | Occurs when a mouse button is released.
NewStream | Occurs when a new stream is started in a station.
OpenStateChange | Occurs when the Windows Media Player control changes its open state.
PlayStateChange | Occurs when the Windows Media Player control changes its play state.
PositionChange | Occurs when the current media position moves to a new position.
ReadyStateChange | Occurs when the Windows Media Player control's state of readiness changes.
ScriptCommand | Occurs when a synchronized command or URL is received.

Warning The following methods, properties, and events are not supported in this version of Windows Media Player for Mac:

Methods

  • FastForward
  • FastReverse
  • GetCodecURL
  • GetMediaParameter
  • GetMediaParameterName
  • GetMoreInfoURL
  • GetStreamGroup
  • GetStreamName
  • GetStreamSelected
  • IsSoundCardEnabled
  • SetCurrentEntry
  • ShowDialog
  • StreamSelect

    Properties

  • AllowChangeDisplaySize
  • AllowScan
  • AnimationAtStart
  • AudioStream
  • AutoRewind
  • AutoSize
  • Balance
  • CanPreview
  • CanScan
  • CaptioningID
  • ClickToPlay
  • CodecCount
  • CreationDate
  • CursorType
  • DisplayBackColor
  • DisplayForeColor
  • DisplayMode
  • DisplaySize
  • EnableContextMenu
  • Enabled
  • EnableFullScreenControls
  • EnablePositionControls
  • EnableTracker
  • ErrorCorrection
  • Language
  • Rate
  • SourceProtocol
  • StreamCount
  • TransparentAtStart
  • VideoBorder3D
  • VideoBorderColor
  • VideoBorderWidth

    Events

  • Disconnect
  • DisplayModeChange


Windows Media Player Version for Solaris 6.3

The following methods, properties, and events are currently supported for use with the Windows Media Player for Solaris 6.3 using the Netscape Navigator plug-in.

Windows Media Player for Solaris 6.3 supports the following methods.

Method | Description
AboutBox | Displays version and copyright information about the Windows Media Player control.
Cancel | Cancels the Open method before the file completes opening.
GetCodecDescription | Retrieves the descriptive name of the given codec.
GetCodecInstalled | Retrieves a value specifying whether a given codec is installed.
GetCurrentEntry | Retrieves the current clip being played by the Windows Media Player control.
GetMarkerName | Retrieves the name of a marker, given its marker number.
GetMarkerTime | Retrieves a value specifying the presentation time of a given marker.
GetMediaInfoString | Retrieves show or clip information.
Next | Jumps to the next clip in a playlist.
Open | Asynchronously opens a specified clip.
Pause | Suspends playback at the current position in the clip.
Play | Starts playing a clip from the starting position or continues playing a paused or stopped clip.
Previous | Jumps to the previous clip in a playlist.
Stop | Stops playback of the current clip.

Windows Media Player for Solaris supports the following properties.

Property | Description
AutoStart | Sets or retrieves a value specifying whether to start playing the clip automatically.
Bandwidth | Retrieves the bandwidth of the current clip in bits per second.
BaseURL | Retrieves a value specifying the base URL.
BufferingCount | Retrieves a value specifying the number of times buffering occurred during playback of a clip.
BufferingProgress | Retrieves a value specifying the percentage of buffering completed.
BufferingTime | Retrieves a value specifying the buffering time in seconds.
CanSeek | Retrieves a value specifying whether the current file has the ability to seek to a specific time.
CanSeekToMarkers | Retrieves a value specifying whether markers in the file can be located with a seek operation.
CaptioningID | Retrieves a value representing the name of the frame or control that displays captioning.
ChannelDescription | Retrieves the station description.
ChannelName | Retrieves the station name.
ChannelURL | Retrieves a value representing the URL of the station metafile.
ClientID | Retrieves a value indicating the unique ID of a client.
ConnectionSpeed | Retrieves a value specifying the bandwidth selected during setup.
ContactAddress | Retrieves a value representing the station's contact address.
ContactEmail | Retrieves a value representing the station's e-mail address.
ContactPhone | Retrieves a value representing the station's contact telephone number.
CurrentMarker | Sets or retrieves a value indicating the current marker number.
CurrentPosition | Sets or retrieves a value representing the clip's current position, in seconds.
DefaultFrame | Sets or retrieves a value representing the default target HTTP frame.
DisplaySize | Sets or retrieves a value specifying the size of the image display window.
Duration | Retrieves a value indicating the clip's playing time in seconds.
EntryCount | Returns the number of entries contained in the current Advanced Stream Redirector (ASX) file.
ErrorCode | Retrieves a value specifying the current error code.
ErrorDescription | Retrieves a value specifying the description of the current error state.
FileName | Sets or retrieves a value specifying the name of the clip to play.
HasError | Retrieves a value specifying whether the Windows Media Player control currently has an error.
HasMultipleItems | Retrieves a value specifying whether the current clip contains multiple items (playlists).
ImageSourceHeight | Retrieves a value specifying the original image height of the current clip, in pixels.
ImageSourceWidth | Retrieves a value specifying the original image width of the current clip, in pixels.
InvokeURLs | Sets or retrieves a value specifying whether the Windows Media Player control automatically invokes URLs in a browser.
IsBroadcast | Retrieves a value specifying whether the source is broadcast.
IsDurationValid | Retrieves a value specifying whether the value of the Duration property is valid.
Language | Retrieves a value specifying the current locale used for national language support.
LostPackets | Retrieves a value specifying the number of packets lost during transmission of the stream.
MarkerCount | Retrieves a value specifying the number of markers in the current clip.
Mute | Sets or retrieves a value indicating the current mute state of the Windows Media Player control.
OpenState | Retrieves a value indicating the state of the content source.
PlayCount | Sets or retrieves a value indicating the number of times a clip plays.
PlayState | Retrieves a value indicating the state of the Windows Media Player operation.
PreviewMode | Sets or retrieves a value specifying whether Windows Media Player is in preview mode.
Rate | Sets or retrieves a value specifying the clip's playback rate.
ReadyState | Retrieves a value specifying the state of readiness of the Windows Media Player control.
ReceivedPackets | Retrieves a value specifying the number of packets received.
ReceptionQuality | Retrieves a value specifying the percentage of packets received in the last 30 seconds.
RecoveredPackets | Retrieves a value specifying the number of packets recovered.
SAMIFileName | Sets or retrieves a value specifying the file that contains the information needed for closed captioning.
SAMILang | Retrieves a value specifying the language displayed for closed captioning.
SAMIStyle | Retrieves a value representing the closed captioning style.
SelectionEnd | Sets or retrieves a value specifying the time when playback of the current clip will stop.
SelectionStart | Sets or retrieves a value specifying where playback of the current clip will begin.
SendErrorEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends error events.
SendKeyboardEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends keyboard events.
SendMouseClickEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends mouse click events.
SendMouseMoveEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends mouse move events.
SendOpenStateChangeEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends open state change events.
SendPlayStateChangeEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends play state change events.
SendWarningEvents | Sets or retrieves a value specifying whether the Windows Media Player control sends warning events.
ShowAudioControls | Sets or retrieves a value specifying whether the audio controls appear on the control bar.
ShowCaptioning | Sets or retrieves a value specifying whether the closed caption area is visible and closed captioning is enabled.
ShowControls | Sets or retrieves a value specifying whether the control bar is visible.
ShowDisplay | Sets or retrieves a value specifying whether the display panel is visible.
ShowGotoBar | Sets or retrieves a value specifying whether the Go To bar is visible.
ShowPositionControls | Sets or retrieves a value specifying whether the position controls appear on the control bar.
ShowStatusBar | Sets or retrieves a value specifying whether the status bar is visible.
ShowTracker | Sets or retrieves a value specifying whether the trackbar is visible.
SourceLink | Retrieves a value specifying the path to the current clip.
Volume | Sets or retrieves a value specifying the volume, in hundredths of a decibel.

Windows Media Player for Solaris supports the following events.

Event | Description
Buffering | Occurs when the Windows Media Player control begins or ends buffering.
Click | Occurs when a user clicks the mouse with the cursor on the Windows Media Player control.
DblClick | Occurs when a user double-clicks the mouse with the cursor on the Windows Media Player control.
Disconnect | Occurs when the Windows Media Player control is disconnected from the server.
DisplayModeChange | Occurs when the DisplayMode property changes.
EndOfStream | Occurs when the end of the clip is reached.
Error | Occurs when the Windows Media Player control has an error condition.
KeyDown | Occurs when a key is pressed.
KeyPress | Occurs when a key is pressed and released.
KeyUp | Occurs when a key is released.
MarkerHit | Occurs when a marker is reached.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved.
MouseUp | Occurs when a mouse button is released.
NewStream | Occurs when a new stream is started in a station.
OpenStateChange | Occurs when the Windows Media Player control changes its open state.
PlayStateChange | Occurs when the Windows Media Player control changes its play state.
PositionChange | Occurs when the current media position moves to a new position.
ReadyStateChange | Occurs when the Windows Media Player control's state of readiness changes.
ScriptCommand | Occurs when a synchronized command or URL is received.
Warning | Occurs when the Windows Media Player control encounters a possible problem.


Previous Version

The Windows Media Player Object Model version 6.4 is a Microsoft® ActiveX® control used for adding multimedia playback capabilities to COM-based documents and applications, as well as Web pages. It provides a programming interface for rendering a variety of network streaming and nonstreaming multimedia formats. The Windows Media Player control version 6.4 incorporates many of the features of the Microsoft® ActiveMovie™ control and the Microsoft® NetShow™ Player version 2.0 control, as well as many new features.

Section | Description
About the Version 6.4 Player Object Model | Introduces the basics of the Windows Media Player control version 6.4.
Version 6.4 Player Object Model Guide | Describes how to use and program the control.
Version 6.4 Object Model Reference | Provides a reference for each method, property, and event exposed by the Windows Media Player control.

This section of the SDK also includes information about the Windows Media Player 6.4 Netscape plug-in and the Windows Media Player for Solaris 6.3 plug-in.


About the Version 6.4 Player Object Model

This topic applies to Windows Media Player version 6.4 only.

This section introduces the basics of the Version 6.4 Windows Media Player control, which enables you to easily enrich static content with dynamic, interactive functionality. The Windows Media Player control is a Microsoft® ActiveX® control. You can insert it into Microsoft® Visual Basic® applications or embed it in Web pages, controlled through Microsoft® Visual Basic® Scripting Edition (VBScript) or Microsoft® JScript®.

To use all of the script commands covered in this section, you must have Windows Media Player version 6.4 installed on your machine.

For more information about developing applications using ActiveX controls, see the Microsoft Component Object Model Web pages.

For information about scripting ActiveX controls, see the Microsoft Scripting Web pages.

This section contains the following articles.

  • Introducing the Version 6.4 Windows Media Player Object Model
  • What's New for the Windows Media Player Object Model?
  • What Background Do You Need?
  • Placing the Windows Media Player Control in a Web Page
  • Placing the Windows Media Player Control in a Visual Basic Application
  • Architecture


Introducing the Version 6.4 Windows Media Player Object Model

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control exposes methods and properties for manipulating multimedia playback from a Web page or application. Functionality exposed by the methods and properties includes:

  • Building custom user interfaces on top of the Windows Media Player control. Buttons, boxes, and menus can be incorporated into your Web page or application for administering the control.
  • Performing VCR-like functions, such as start, stop, pause, fast-forward, rewind, mute, and volume adjustment.
  • Monitoring stream and station performance.
  • Retrieving information about the content, such as the title, author, and copyright date.

Your application or Web page can also be designed to respond to event messages created by the Windows Media Player control. Events that cause the Windows Media Player control to create an event message include the following:

  • Warnings and errors encountered by the control.
  • Changes in the state of the stream, such as from a play state to a paused state.
  • Keyboard and mouse input.
  • Control disconnecting from a stream server.
  • Script commands received by the control.

Windows Media Player is also provided as a stand-alone player application based on the same technology as the Windows Media Player control. However, the control enables you to create a user interface unique to your content, to process any type of script commands, and to integrate multimedia presentations into larger Web applications.


What's New for the Windows Media Player Object Model?

This topic applies to Windows Media Player version 6.4 only.

New multimedia functionality has been added to the Windows Media Player control since its last release. These changes are valid for versions of the Windows Media Player control available in Microsoft® Internet Explorer 5, the Microsoft® Windows® 98 OEM Service Release (OSR), and Microsoft® Windows 2000.

The Windows Media Player control now supports playback of Digital Video Disc (DVD) media. Microsoft has included scripting support for nearly all DVD-specific capabilities, such as title and chapter seeking, video angle changes, and multi-language support. The added features and scripting support are listed in detail in Using DVD with the Version 6.4 Windows Media Player Control.

The Windows Media Player control now also supports playback for Compact Disc (CD) audio. By specifying "CDAUDIO:" for the input file name, you can play an entire CD as if it were a single audio stream. The Windows Media Player control treats individual tracks of the CD as markers within the audio stream. For more information, see Compact Disc Audio Playback.

Microsoft has made all Windows Media Player functionality available to Web scripting languages such as Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft® JScript®. This enables you to embed the Windows Media Player control in HTML applications and create custom faceplates for your multimedia presentations. You can create an entire user interface on a faceplate that is tailored for the media you are presenting. The Faceplate Authoring Guide walks you through the process of creating a faceplate and provides sample code demonstrating the concepts discussed.

As part of the new faceplate functionality, Microsoft has added script support for accessing information contained in Windows Media metafiles and embedding as much custom information within each media file as you like. The Windows Media Player control reads the information from the Windows Media metafile, and scripts can then retrieve the information and display it on a faceplate.

The following scripting and Windows Media metafile elements are new to this release of the Windows Media Player control.

  • Windows Media Metafile Elements
    • PARAM Element—Defines a custom parameter associated with a clip or show.
  • Scripting Methods
    • GetCurrentEntry—Retrieves the current clip being played by the Windows Media Player control.
    • GetMediaParameter—Retrieves the value of the specified parameter for an indexed Windows Media metafile entry.
    • GetMediaParameterName—Retrieves the name of the specified parameter for an indexed ASX entry.
    • SetCurrentEntry—Selects a clip for playback by the Windows Media Player control.
    • ShowDialog—Displays a modal dialog box containing a specified Windows Media Player dialog.
  • Scripting Properties
    • EntryCount—Retrieves the number of entries contained in the current Windows Media metafile.


What Background Do You Need?

This topic applies to Windows Media Player version 6.4 only.

To use the Windows Media Player control in a Web page, you need to know at least the fundamentals of HTML. The article Placing the Windows Media Player Control in a Web Page shows how to embed a Windows Media Player control with a standard user interface, using the HTML OBJECT tag.

If you know a Web scripting language, dynamic HTML (DHTML), or how to create a cascading style sheet (CSS), you can create sophisticated user interfaces for the Windows Media Player control. Using the Windows Media Player control with scripting languages enables you to customize the operation of the control and coordinate it with other graphics on the Web page. Supported scripting languages include Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft® JScript® (compatible with ECMA 262 language specification). If you are familiar with HTML applications, you can create multimedia faceplates viewable with Microsoft® Internet Explorer 5.

If you have some knowledge of Microsoft® Visual Basic® and the Visual Basic 5.x development environment, you can also use the Windows Media Player control to create multimedia applications and Microsoft® ActiveX® controls.


Placing the Windows Media Player Control in a Web Page

This topic applies to Windows Media Player version 6.4 only.

As a Microsoft® ActiveX® control, the Windows Media Player control exposes methods, properties, and event support to other Microsoft® Windows® applications. Although ActiveX controls can be used as components in a variety of programming environments, they are extremely well suited for use in Web pages. ActiveX controls can add exciting dynamic content to previously static Web pages, and they are easy to distribute over networks.

By using a scripting language, such as Microsoft® Visual Basic® Scripting Edition (VBScript) or Microsoft® JScript®, you can easily embed the Windows Media Player control in an HTML file. This article explains how to do this, using VBScript for the examples.

This article contains the following sections.

  • Embedding the Windows Media Player Control
  • Setting Control Properties with the PARAM Tag
  • Adding a Simple User Interface for the Control
  • Adding the Scripting Code
  • Simple Windows Media Player Control Web Page


Embedding the Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

The HTML OBJECT tag is used to embed ActiveX objects into an HTML file. The following code shows how to use the OBJECT tag to insert the Windows Media Player control.

<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
  CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95"
  STANDBY="Loading Windows Media Player components..."
  TYPE="application/x-oleobject">
</OBJECT>

The following OBJECT tag attributes are required.

  • ID: The name used to reference this instance of the control in scripts.
  • CLSID: The Class Identifier (CLSID) of the Windows Media Player control, which is used by the Web browser to create the ActiveX object on the page.

Using the CODEBASE attribute is strongly recommended, but optional. It contains a Uniform Resource Locator (URL) pointing to a location where the Windows Media Player control can be downloaded from, if it is unavailable on a user's system. In addition to the address of the Windows Media Player object, the CODEBASE attribute can optionally specify a version number of the Windows Media Player control.

The Windows Media Player control is available for download on the Microsoft.com Web site, packaged as a .cab (cabinet) file.


Setting Control Properties with the PARAM Tag

This topic applies to Windows Media Player version 6.4 only.

One way to set the properties of a control in a Web page is to add PARAM tags between the OBJECT tags. This method is ideal for setting properties at design time. The following code shows you the OBJECT tag with some PARAM tags added.

<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
  CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95"
  STANDBY="Loading Windows Media Player components..."
  TYPE="application/x-oleobject">

  <PARAM NAME="FileName" VALUE="C:\ASFRoot\Welcome.asf">
  <PARAM NAME="ShowControls" VALUE="False">
  <PARAM NAME="AutoRewind" VALUE="True">
  <PARAM NAME="AutoStart" VALUE="False">
</OBJECT>

The PARAM tags used in the preceding example have two attributes: the first is the name of the property being set, and the second specifies the value of the property. In the previous example, the first PARAM tag sets the FileName property to C:\ASFRoot\Welcome.asf. The remaining PARAM tags initialize the values of the AutoRewind property to true, the ShowControls property to false, and the AutoStart property to false.


Adding a Simple User Interface for the Control

This topic applies to Windows Media Player version 6.4 only.

Adding a few buttons is the simplest way to demonstrate Windows Media Player control operation. Add the following three button controls to the body of your HTML page: one to start the Windows Media Player control, one to stop it, and one to display the current version of the Windows Media Player control.

<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop">
<INPUT TYPE="BUTTON" NAME="BtnAbout" VALUE="About">


Adding the Scripting Code

This topic applies to Windows Media Player version 6.4 only.

Scripting code adds interactivity to your page, enabling you to respond programmatically to events, to call methods, and to change run-time properties. First, you must use a SCRIPT tag to notify the browser which scripting language you intend to use. Include your script commands within HTML comment tags so browsers that do not support scripting do not render your code as text. Put the SCRIPT tag anywhere within the BODY of your HTML file and embed the comment-surrounded code within the opening and closing SCRIPT tags.

The following code calls the Windows Media Player control methods in response to events triggered by clicking the button controls.

<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnAbout_OnClick
   MediaPlayer1.AboutBox
End Sub

Sub BtnPlay_OnClick
    MediaPlayer1.Play
End Sub

Sub BtnStop_OnClick
    MediaPlayer1.Stop
    MediaPlayer1.CurrentPosition = 0
End Sub
-->
</SCRIPT>

Each subroutine is attached to a specific button that was defined previously. When an event is triggered by a button click, the code makes a call (or series of calls) to the Windows Media Player control, specifying the action to be taken.


Simple Windows Media Player Control Web Page

This topic applies to Windows Media Player version 6.4 only.

By combining the elements previously discussed in this article, you can see how the pieces fit together in the following sample code.

<HTML>
<HEAD><TITLE>Windows Media Player Test</TITLE></HEAD>
<BODY>

<OBJECT ID="MediaPlayer1" WIDTH=320 HEIGHT=240
  CLASSID="CLSID:22D6f312-B0F6-11D0-94AB-0080C74C7E95"
  STANDBY="Loading Windows Media Player components..."
  TYPE="application/x-oleobject">

  <PARAM NAME="FileName" VALUE="C:\ASFRoot\Welcome.asf">
  <PARAM NAME="ShowControls" VALUE="False">
  <PARAM NAME="AutoRewind" VALUE="True">
  <PARAM NAME="AutoStart" VALUE="False">
</OBJECT>

<BR>
<INPUT TYPE="BUTTON" NAME="BtnPlay" VALUE="Play">
<INPUT TYPE="BUTTON" NAME="BtnStop" VALUE="Stop">
<INPUT TYPE="BUTTON" NAME="BtnAbout" VALUE="About">

<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnAbout_OnClick
   MediaPlayer1.AboutBox
End Sub

Sub BtnPlay_OnClick
    MediaPlayer1.Play
End Sub

Sub BtnStop_OnClick
    MediaPlayer1.Stop
    MediaPlayer1.CurrentPosition = 0
End Sub
-->
</SCRIPT>

</BODY>
</HTML>

Try this code with a multimedia file on your computer. Copy and paste the code into a text file, and change the value of the FileName attribute to specify the protocol, relative path, and name of the clip you want to play.


Placing the Windows Media Player Control in a Visual Basic Application

This topic applies to Windows Media Player version 6.4 only.

Microsoft® ActiveX® technology is an ideal way to add multimedia content to a Web page. Under certain circumstances, however, a stand-alone application may be more appropriate. This section describes the basic steps used to create a simple application with Microsoft® Visual Basic® 5.0 and the Windows Media Player control. This section assumes the reader has some knowledge of Visual Basic and the Visual Basic 5.0 development environment.

Note Stand-alone applications do not support DVD-Video playback.

This article contains the following sections.

  • Installing the Windows Media Player Control
  • Inserting the Windows Media Player Control
  • Adding Button Controls
  • Compiling and Running


Installing the Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

If the Windows Media Player control is properly installed on your system, the Visual Basic development environment provides an easy procedure for installing the control in your project's toolbox. The Windows Media Player control is listed as Microsoft Windows Media Player on the Controls tab of the Components dialog box.

This example assumes that your project is a standard executable with one form.


Inserting the Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

First add the Windows Media Player control to the form. Change the FileName property to the name of a multimedia file on your computer (for example, C:\ASFRoot\Welcome.asf).

Change the AutoStart property to false and the AutoRewind property to true. You will add a custom user interface to the form, so change the ShowControls property to false.

Set the ClipControls property to false. By default, Visual Basic sets this property to true. When the Windows Media Player control is embedded in a Visual Basic form, however, this property must be false to avoid problems in repainting.


Adding Button Controls

This topic applies to Windows Media Player version 6.4 only.

Next, add three CommandButton controls to your form, below the Windows Media Player control object. Change the caption on the first button to Start, on the second to Stop, and on the third to About. Add the following event procedures to the form's code view, so that Visual Basic will recognize when the buttons are clicked.

Private Sub Command1_Click()
    MediaPlayer1.Play
End Sub

Private Sub Command2_Click()
    MediaPlayer1.Stop
End Sub

Private Sub Command3_Click()
    MediaPlayer1.AboutBox
End Sub

Now, you can play and stop a multimedia file by clicking the Start and Stop buttons, respectively. After clicking the About button, a message box appears containing copyright and version information for the Windows Media Player control.


Compiling and Running

This topic applies to Windows Media Player version 6.4 only.

Start your application and check the results. If you specified a valid multimedia file in the FileName property, clicking the Play button should start the presentation. Clicking the Stop button stops the presentation. The About button displays a dialog box containing the version number of the Windows Media Player control.


Architecture

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control is built on Microsoft® DirectShow® technology. DirectShow is based on Component Object Model (COM) architecture, which employs components called filters that can be plugged in to process multimedia data. Each filter is designed to receive digital input, process the data, and pass the results on to the next filter. The filters are arranged in a configuration called a filter graph.

DirectShow technology is based on several Microsoft services, including:

  • Microsoft® DirectDraw® for two-dimensional graphics hardware acceleration.
  • Microsoft® DirectSound® for audio mixing and low-latency audio.
  • Microsoft® Direct3D® for three-dimensional graphics hardware acceleration.

Filters and filter graphs can be created by implementing COM interfaces that use the class libraries and documentation provided by the DirectShow Software Development Kit (SDK). However, it is not necessary to understand Microsoft® Visual C++® programming or COM to use the Windows Media Player control.

The following diagram illustrates the relationship between DirectShow and the Windows Media Player control.

This section contains the following articles:

  • Compatibility Modes
  • Content Formats
  • Codecs


Compatibility Modes

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control is designed to be a universal player for all types of multimedia data. It works equally well rendering content served by Windows Media Services and Microsoft® DirectShow® local playback media types. The Windows Media Player control incorporates many of the attributes supported by the earlier Microsoft® NetShow™ Player version 2.0 control and by the Microsoft® ActiveMovie™ control, along with new methods, properties, and events. In addition, the Windows Media Player control can operate in one of the following three modes to provide compatibility with the NetShow Player version 2.0 and ActiveMovie controls.

  • MediaPlayer mode—The control supports all of the methods, properties, and event notifications documented in this SDK.
  • NSPlay mode—The control exposes the methods, properties, and events supported for the NetShow Player version 2.0 control.
  • ActiveMovie mode—The control exposes the methods, properties, and events supported for the ActiveMovie control.

All three modes provide the enhanced streaming and playback capabilities of Windows Media Player; however, each mode supports its own set of attributes.

The class identifier (CLSID) used to create an instance of the control determines the mode of operation. Using one of the CLSIDs previously reserved for NetShow Player control or the ActiveMovie control creates an instance of the Windows Media Player control in that alternate mode. As a result, applications and Web pages created with these controls can use the improved performance of Windows Media Player with little or no change to their code. In many cases, you can update a Web page simply by changing the CODEBASE attribute to specify the cabinet (.cab) file containing the Windows Media Player control.

Important Installing the NetShow Player version 2.0 control or the ActiveMovie control on your development platform after installing the Windows Media Player control causes unexpected results.

This article contains the following sections.

  • Forward Compatibility
  • Backward Compatibility
  • Compatibility Considerations
  • Control CLSIDs


Forward Compatibility

This topic applies to Windows Media Player version 6.4 only.

In addition to the attributes supported when you create an instance of the control in NSPlay or ActiveMovie mode, a new property named MediaPlayer is exposed. This property provides access to the methods and properties supported in MediaPlayer mode. Use the following syntax to access MediaPlayer-mode attributes when the control is operating in NSPlay or ActiveMovie mode.

AlternateMode.MediaPlayer.Attribute

AlternateMode is the instance of the player control object ID created by using the NSPlay or ActiveMovie CLSID, and Attribute is any method or property exposed by the control in MediaPlayer mode. For example, if your script embedded the NetShow Player 2.0 control with an ID attribute equal to NSPlay1, you would access the Volume property by using the following code.

NSPlay1.MediaPlayer.Volume


Backward Compatibility

This topic applies to Windows Media Player version 6.4 only.

In addition to forward compatibility, the control provides access to NetShow Player 2.0 and ActiveMovie attributes in MediaPlayer mode. Two properties, NSPlay and ActiveMovie, are exposed when an instance of the control is created as usual. Use the following syntax to access NetShow Player or ActiveMovie properties and methods when the control is operating in MediaPlayer mode.

NormalMode.NSPlay.Attribute

Or

NormalMode.ActiveMovie.Attribute

NormalMode is the instance of the player control created with the Windows Media Player CLSID, and Attribute is any method or property exposed by the control in an alternate mode. For example, to access the Author property of the NetShow Player 2.0 control from code written for the Windows Media Player control, use the following:

MediaPlayer1.NSPlay.Author


Compatibility Considerations

This topic applies to Windows Media Player version 6.4 only.

Operating in forward or backward compatibility modes has the following restrictions.

  • The control only fires events that are supported for the mode in which an instance of the control is created.
  • Many methods and properties exposed by the Windows Media Player control have the same name as properties and methods exposed by the NetShow version 2.0 and ActiveMovie controls. Most of these attributes exhibit the functionality of their predecessors. However, instances of methods with the same name and different behavior always function in the mode in which they are created.
  • Mode-switching is only allowed on properties accessed at run time. You cannot set properties for alternate modes at design time.


Control CLSIDs

This topic applies to Windows Media Player version 6.4 only.

Following is a list of the CLSIDs used to create an instance of the control in each mode.

Control mode | CLSID
MediaPlayer | 22D6F312-B0F6-11D0-94AB-0080C74C7E95
NSPlay | 2179C5D3-EBFF-11cf-B6FD-00AA00B4E220
ActiveMovie | 05589FA1-C356-11CE-BF01-00AA0055595A


Content Formats

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control acts as a universal player for rendering most standard multimedia formats. This includes stored and live content in network streaming formats, as well as non-streaming formats. Network streaming formats supported by Windows Media Player include the following:

  • Windows Media Audio (WMA) and Windows Media Audio metafiles (WAX)
  • Windows Media Video (WMV) and Windows Media Video metafiles (WVX)
  • Windows Media files (ASF) and Windows Media metafiles (ASX).
  • Video On Demand (VOD)
  • Moving Picture Experts Group standard 1 and 2 (MPEG-1, MPEG-2), including MPEG Layer-3 audio(MP3).
  • Closed captioning (SMI, SAMI)

Non-streaming (local playback) formats supported by the Windows Media Player control include all of the network streaming formats previously listed, plus the following:

  • Compact Disc Audio (CD)
  • Digital Video Disc (DVD)
  • Audio-Video Interleaved (AVI)
  • Apple QuickTime® (QT, MOV), version 2 and lower.
  • Musical Instrument Digital Interface (MIDI)
  • Indeo™ Video 5
  • Waveform Audio (WAV)
  • Sound File (SND)
  • UNIX audio (AU)
  • Audio Interchange File Format (AIFF)


Codecs

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control supports all of the major multimedia compression/decompression algorithms (codecs) in use today. The Windows Media Player control automatically detects which codec is needed to decompress incoming data. Because Windows Media Player is based on the extensible filter-based architecture of Microsoft® DirectShow®, it is easy to add support for new codecs as they are created. The Windows Media Player control also supports non-filter-based codecs, such as Audio Compression Manager (ACM) and Video Compression Manager (VCM).

Because the decompression takes place on the client computer, some codecs must reside on the client. In most cases, the Windows Media Player control .ocx file is packaged with the appropriate codecs into a .cab file before it is distributed to clients. Other codecs can be downloaded and installed after the Windows Media Player is installed.

For more information on this topic, consult Codecs in the Windows Media Services section of the Microsoft Web site.


Version 6.4 Player Object Model Guide

This guide contains the following sections.

  • Using the Version 6.4 Windows Media Player Object Model
  • Using DVD with the Version 6.4 Windows Media Player Object Model
  • Faceplate Authoring Guide
  • Windows Media Player Plug-in for Netscape Navigator
  • Windows Media Player for Solaris 6.3


Using the Version 6.4 Windows Media Player Object Model

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control exposes a variety of methods, properties, and events for creating customized applications and Web pages. This section groups the control's attributes into categories by functionality. It contains the following articles.

  • Playback Methods and Properties
  • Customizing the User Interface
  • Using Playlists
  • Retrieving Presentation Information
  • Closed Captioning
  • Processing Embedded Script Commands
  • Capturing Keyboard and Mouse Events
  • Monitoring Stream Status and Network Reception
  • Error Handling
  • Compact Disc Audio Playback


Playback Methods and Properties

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control supports several attributes for manipulating playback of content. In addition to methods for playing, pausing, and stopping media content, the Windows Media Player exposes attributes for the following:

  • Scanning—analogous to fast-forward and rewind functions on a VCR.
  • Seeking—proceeding directly to a particular presentation time marked in the clip.

This article contains the following sections.

  • Playback
  • Audio Control
  • Scanning
  • Seeking


Playback

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides two techniques for specifying the media title (clip) to be played. You can set the FileName property, or call the Open method. If the value of the AutoStart property is true, the desired clip begins to play when the FileName property is set to the URL of that clip. If AutoStart is false, the Windows Media Player control does not start playback until the Play method is called. The Open method starts the stream asynchronously, unlike the Play method, which waits for other processes to finish before starting.

The Windows Media Player control provides the following VCR-like attributes for controlling stream playback:

  • Play, Stop, and Pause methods, to start, stop, and pause the stream.
  • PlayCount property to set the number of times a file plays.
  • AutoRewind property to determine whether to return to the start of the clip when it stops playing.


Audio Control

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides the following properties for regulating audio:

  • Balance property, for determining the balance of sound between left and right speakers.
  • Volume property, for raising or lowering volume.
  • Mute property, for turning audio on and off.

You can add controls for handling audio to the control bar by setting the ShowAudioControls property to true.


Scanning

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides the following attributes for scanning:

  • FastForward method, to rapidly scan forward through a clip.
  • FastReverse method, to rapidly scan backward through a clip.
  • Rate property, to change the rate at which playback occurs.

The CanScan and AllowScan properties must be true before a clip can be scanned.


Seeking

This topic applies to Windows Media Player version 6.4 only.

Some types of multimedia streams support seeking to arbitrary times in the presentation, as well as seeking to markers. A marker is a pointer to a specific time in a multimedia file, written into the file at authoring time. Windows Media Player can seek directly to the time specified by a marker, enabling viewers to skip forward or backward in the presentation. Attributes supported for seeking include:

  • MarkerCount property, which specifies the total number of markers in the clip.
  • CurrentMarker, GetMarkerName and GetMarkerTime methods, which retrieve marker information.
  • MarkerHit event, which provides notification when a marker is encountered.
  • CurrentPosition property, which can be used to set playback to a specified point in the clip. CurrentPosition is measured in seconds from the start of the clip.
  • PositionChange event, which notifies your application when the CurrentPosition property is set.

The CanSeek property must be true to seek to an arbitrary time, and the CanSeekToMarkers property must be true to seek to a marker.


Customizing the User Interface

This topic applies to Windows Media Player version 6.4 only.

You can control the way the Windows Media Player control looks when it is embedded in a Web page. You can make it look just like the Windows Media Player application, complete with standard control buttons, a trackbar, and text display for the media file information. You can enable just the video display panel and control buttons of Windows Media Player, so that the video playback takes up the least amount of space on a page. For audio-only playback, you can even disable all display of the Windows Media Player control, and create your own control buttons and text displays in HTML.

The display element of the Windows Media Player control is determined by a number of properties that are set when the control is created on the Web page. This article is a guide to how the values of those properties affect the way the Windows Media Player control is displayed.

This article contains the following sections.

  • User Interface Elements
  • Sizing the Windows Media Player Control
  • Additional User Interface Attributes
  • Faceplates


User Interface Elements

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control also exposes properties that determine which elements of the user interface are enabled and displayed to the end user. The following figure depicts the elements of the Windows Media Player user interface.

elements of the user interface

The following properties determine which user interface elements are displayed.

  • The ShowControls property specifies whether the control bar is displayed. The control bar contains playback controls. Optionally, it has audio and position controls as well.
  • The ShowAudioControls property specifies whether the mute button (speaker icon) and volume slider control are displayed on the control bar.
  • The ShowPositionControls property specifies whether the fast forward, fast rewind, skip ahead, skip previous, and preview buttons are displayed on the control bar.
  • The ShowTracker property specifies whether the trackbar is displayed. The trackbar indicates the progress of the current clip. End users can seek to any position in the clip by clicking and dragging the progress indicator on the trackbar. The trackbar is only visible when the control bar is enabled.
  • The ShowDisplay property specifies whether the display panel is displayed. The display panel provides show and clip information.
  • The ShowCaptioning property specifies whether the closed captioning display panel is displayed.
  • The ShowGotoBar property specifies whether the Go To bar is displayed.
  • The ShowStatusBar property specifies whether the status bar is displayed.


Sizing the Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

One powerful feature of Windows Media Player is its ability to stretch or shrink a clip from its original dimensions. Changing clip dimensions can be done programmatically by changing the value of the DisplaySize property. This property can be set to a wide range of values, from one half the size of the source image to full-screen display. It can only be set when the value of the AllowChangeDisplaySize property is true.

For Windows-based applications, the initial dimensions of the Windows Media Player control are determined at design time. For example, in Microsoft® Visual Basic® you select the control from the toolbox and use the mouse to draw the Windows Media Player object on the form. On a Web page with an embedded control, the HEIGHT and WIDTH parameters of the OBJECT tag determine the initial size of the control. If the height and width are specified, and the value of the AutoSize property is false, media clips conform to the dimensions of the Windows Media Player.

Specifying the size is an ideal way to tailor Windows Media Player to specific media content. However, because clips can be stored and streamed in a variety of shapes and sizes, it is often advantageous to have the Windows Media Player conform to the dimensions of the clip. Setting the AutoSize property to true allows the Windows Media Player to stretch or shrink to accommodate the clip played at the specified display size.

When the AutoSize and ShowControls properties are both true, the control bar might determine the minimum width of the Windows Media Player. The Windows Media Player can resize itself no smaller than the control bar with all of its buttons displayed. Adding position and audio controls increases the width of the control bar. The following table describes the different widths of the control bar.

Width | ShowAudioControls | ShowPositionControls
Narrowest | False | False
Wide | True | False
Wider | False | True
Widest | True | True

If the AutoSize property is false, the HEIGHT and WIDTH parameters specify the dimensions of the entire control, including the control panel, display panel, status bar, and so forth. If the specified height is insufficient for both the controls and the video display, the video shrinks to fill the available space. If the specified width is insufficient to accommodate the control bar, buttons on the right side of the control bar are cut off.

If the Windows Media Player control is embedded in a Web page, using HEIGHT and WIDTH parameters has the following effects:

  • The DisplaySize property defaults to mpFitToSize. Clips are sized to fit into the specified dimensions.
  • The AutoSize property defaults to false.

Embedding the Windows Media Player control without specifying HEIGHT and WIDTH parameters has the following effects:

  • The DisplaySize property defaults to mpDefaultSize. Clips are sized to the dimensions of the source image.
  • The AutoSize property defaults to true.


Additional User Interface Attributes

This topic applies to Windows Media Player version 6.4 only.

You can add a colored video border around the display area to tailor the appearance of the Windows Media Player to your Web site. The following properties determine how the video border looks:

  • The VideoBorderWidth property indicates the width in pixels of the video border.
  • The VideoBorderColor property specifies the color of the video border.
  • The VideoBorder3D property specifies whether a three-dimensional border effect is enabled.

The following properties determine the appearance of the control before a title starts playing.

  • The TransparentAtStart property determines whether the Windows Media Player control is visible before it begins rendering data.
  • The AnimationAtStart property determines whether animation displays while the Windows Media Player control is buffering data.


Faceplates

This topic applies to Windows Media Player version 6.4 only.

A faceplate is an HTML application that uses a customized user interface to the Windows Media Player control. It generally uses just the video display panel for video output, or no display at all for audio output. The user interface is typically written in dynamic HTML (DHTML), and uses Web scripts to control the playback. It enables you to customize the look and feel of Windows Media Player to the content it is presenting.

For more information about creating Media Player faceplates, see the Faceplate Authoring Guide.


Using Playlists

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides support for processing playlists. Playlists consist of one or more entries in a Windows Media metafile specifying the location of individual media presentations. The presentation entries are called clips. The Windows Media Player processes each clip in the playlist in sequence. The entire playlist of clips is referred to as a show.

The Windows Media Player control supports the following methods for accessing clips in a playlist:

  • The Next method skips to the next clip in the show.
  • The Previous method skips back to the previous clip in the show.

One feature of Windows Media Player is its ability to play a preview of each clip in a show. The Windows Media Player control exposes the following properties for previewing clips in a playlist.

  • The PreviewMode property specifies whether Windows Media Player is currently in preview mode.
  • The CanPreview property specifies whether Windows Media Player can be in preview mode. This property must be true before PreviewMode can be set to true.

Including one or more PREVIEWDURATION elements in the Windows Media metafile specifies the length of time each clip is previewed. Otherwise, the default preview time is 10 seconds.

When position controls are on the control bar, they include a preview button, which toggles preview mode. To display the control bar with position controls, set the ShowControls and ShowPositionControls properties to true.

You can also use Windows Media metafiles to add watermarks and banners to player applications and Web sites. Metafiles also support seamless stream switching for inserting advertisements. For more information about metafiles, see Windows Media Metafiles and Windows Media Metafile Element Reference.


Retrieving Presentation Information

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control supports streaming media content, as well as playback of local media files. Windows Media Player can render streaming media from computers running Windows Media Services or Microsoft® NetShow™ Theater Server software. Windows Media Player can receive streamed content in one of two ways:

  • By connecting directly to the media server to receive stored or broadcast clips.
  • By monitoring a defined IP address and port (station) for multicast streams.

Many clips and stations contain information describing the media content. The Windows Media Player control exposes several attributes for retrieving this information.

This article contains the following sections.

  • Clips and Shows
  • Stations


Clips and Shows

This topic applies to Windows Media Player version 6.4 only.

The GetMediaInfoString method can retrieve the following information about the clip and show:

  • File name
  • Title
  • Description
  • Author
  • Copyright
  • Rating
  • URLs to the logo icon, watermark, and banner.

Clip information can be stored in the media file, a Windows Media metafile, or both. If the clip information is specified in a Windows Media metafile, the GetMediaInfoString method retrieves the information from the metafile, overriding the information contained in the clip.

Additional information can be placed in PARAM tags for each show and clip within the Windows Media metafile. You can add as many PARAM tags per clip as you like, storing custom information such as "Director," "Producer," or links to related sites. The information contained in these tags is accessed with the GetMediaParameter method.

The following properties return information about the size and duration of each clip:

  • The ImageSourceHeight and ImageSourceWidth properties retrieve the display size of the image window.
  • The Duration property retrieves the length of the clip, in seconds. To determine whether this property contains valid data, check the value of the IsDurationValid property. (For example, during a broadcast the duration might be unknown.)


Stations

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player uses Windows Media Station (.nsc) files to get the information it needs to receive multicast content over the Internet. These files contain information such as stream location and rollover URL, as well as descriptive information about the station. The Windows Media Player control exposes the following properties for retrieving station information:

  • The ChannelDescription property specifies a description of the station.
  • The ChannelName property specifies the name of the station.
  • The ChannelURL property specifies the location of the .nsc file.

Each channel has a contact responsible for the multicast. Channel contact properties include the following:

  • The ContactAddress property specifies the channel contact's address.
  • The ContactEmail property specifies the channel contact's e-mail name.
  • The ContactPhone property specifies the channel contact's phone number.


Closed Captioning

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides an easy means of adding closed captioning to your media presentation. Windows Media Player supports Synchronized Accessible Media Interchange (SAMI) for closed captioning. SAMI (.smi) files contain text strings associated with specified times within the presentation. The text strings appear in the Windows Media Player closed captioning display area as the clip reaches the designated times.

SAMI files can also include conditional text strings for providing closed captioning in different languages, as well as changeable fonts and font sizes to customize the captioning for specific audiences.

The SAMI Closed Captioning Sample shows how you can add closed captioning to your content with .smi files

The Windows Media Player control supports the following properties for SAMI captioning.

  • The SAMIFileName property specifies the name of the .smi file containing the closed captioning text strings.
  • The SAMILang property specifies the closed captioning language. If this property is not set, the language used is the one associated with the first language tag in the .smi file.
  • The SAMIStyle property specifies the font size and style used for the closed captioning.
  • The ShowCaptioning property determines whether the closed captioning display panel is visible.


Processing Embedded Script Commands

This topic applies to Windows Media Player version 6.4 only.

One compelling feature of Windows Media streams is that they can deliver script commands to the Windows Media Player control, along with the audio and video streams. These script commands are pairs of Unicode™ strings synchronized with a particular time in the multimedia stream. The first string identifies the type of command being sent, and the second specifies the command to process. When the stream reaches the time associated with a command, the control sends a ScriptCommand event to the Web page that contains it. An event-handling routine can then respond to this event. The script command strings are passed to the event handler as parameters of the ScriptCommand event.

The Windows Media Player control automatically processes the following types of embedded script commands. Event-handling routines are not necessary to process these types of commands.

  • URL-type Commands
  • FILENAME-type Commands
  • TEXT-type Commands
  • EVENT-type Commands
  • OPENEVENT-type Commands


URL-type Commands

This topic applies to Windows Media Player version 6.4 only.

When the Windows Media Player control receives a URL-type command, the specified URL launches in the user's default browser. If the Windows Media Player control is embedded in an HTML file that uses frames, the URL can be launched in a frame specified by the script command. This allows the Windows Media Player control to continue rendering the multimedia stream in one frame, while the browser renders images or Web pages in another frame. If the script command does not specify a frame, the DefaultFrame property determines the frame in which the new URL is launched.

Note If the HTML file does not use frames, or if the URL-type command is launched in the same frame as the Windows Media Player control, the URL specified by the script command replaces the page rendering the stream.

You can enable or disable automatic processing of URL-type script commands by setting the InvokeURLs property. If this property is false, the Windows Media Player control ignores URL-type commands. The ScriptCommand event is still sent to the container, however, allowing for conditional processing of URL-type commands.

URL-type commands specify the relative location of the URL. The BaseURL property specifies a base HTTP URL, which the Windows Media Player control concatenates with the relative URL. The result is a fully specified URL, passed as the command parameter of the ScriptCommand event.


FILENAME-type Commands

This topic applies to Windows Media Player version 6.4 only.

When the Windows Media Player control receives a FILENAME-type command, it sets the FileName property to the value specified by the command. The Windows Media Player control then opens the file and begins rendering the stream from the new location. The Windows Media Player control always automatically processes FILENAME-type commands; unlike URL-type commands, they cannot be disabled.


TEXT-type Commands

This topic applies to Windows Media Player version 6.4 only.

When the Windows Media Player control receives a TEXT-type command, the content of the command is displayed in the captioning window of the control. The content can be in plain text or HTML.


EVENT-type Commands

This topic applies to Windows Media Player version 6.4 only.

When the Windows Media Player control receives an EVENT-type command, it searches for the NAME attribute of EVENT elements in the Windows Media metafile. If the NAME attribute matches the second string of the script command, the Windows Media Player control executes the entries contained within the EVENT element. An example is to embed a script command for switching streams. For more information, see the Using Windows Media Metafiles for Seamless Stream Switching section of Windows Media Metafiles.


OPENEVENT-type Commands

This topic applies to Windows Media Player version 6.4 only.

When the Windows Media Player control receives an OPENEVENT-type command, it checks the EVENT element in the Windows Media metafile and opens the matching title. It does not play the title until the Windows Media Player control receives the actual event of the same name from an EVENT-type command.


Capturing Keyboard and Mouse Events

This topic applies to Windows Media Player version 6.4 only.

The EnableContextMenu and ClickToPlay properties provide for user input through the image window. If EnableContextMenu is true, right-clicking on the image window opens a context menu that gives the user access to many of the Windows Media Player control properties. When the ClickToPlay property is true, users can start Windows Media Player by clicking the image window.

To receive mouse movement and mouse click events, set the SendMouseMoveEvents and SendMouseClickEvents properties to true. Mouse events include the following:

  • MouseDown. Occurs when the user presses the mouse button.
  • MouseUp. Occurs when the user releases the mouse button.
  • MouseMove. Occurs when the user moves the mouse pointer.
  • Click. Occurs when the user clicks the mouse button while the pointer is over the Windows Media Player.
  • DblClick. Occurs when the user double-clicks the mouse button while the pointer is over the Windows Media Player.

To receive keyboard events, set the SendKeyboardEvents property to true. Keyboard events include the following:

  • KeyDown. Occurs when the user presses a key.
  • KeyUp. Occurs when the user releases a key.
  • KeyPress. Occurs when the user presses and releases a key.


Monitoring Stream Status and Network Reception

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control can provide you with advanced information about the performance of the media playback. Some of this information can be used for proper operation of Windows Media Player in scripts, while other information allows you to monitor the network reception rates for the media file.

For example, when creating a script to operate the "Play" function of Windows Media Player, you would want to use the PlayState property to determine whether Windows Media Player was already playing a media file. The example that follows shows a script that starts Windows Media Player only if it is not currently playing a file (PlayState=2).

<SCRIPT>
function onPlay()
{
  if(MediaPlayer.PlayState!=2)
    MediaPlayer.Play();
}
</SCRIPT>

You could also notify users of any buffering that Windows Media Player is doing with the current file, updating the buffering progress on the Web page while they are waiting for the playback to begin.

Stream status properties include:

  • PlayState
  • OpenState
  • Bandwidth

Supported events include:

  • OpenStateChange (Occurs only when the SendOpenStateChangeEvents property is true.)
  • PlayStateChange (Occurs only when the SendPlayStateChangeEvents property is true.)
  • EndOfStream
  • NewStream

Network reception properties include:

  • ReceptionQuality
  • ReceivedPackets
  • LostPackets

Attributes for monitoring buffering include:

  • BufferingTime property
  • BufferingCount property
  • BufferingProgress property
  • Buffering event


Error Handling

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides built-in error support by displaying error messages in dialog boxes and on the status bar. Alternatively, you can add error handling to your application by processing error events. If the SendErrorEvents property is true, error message boxes are disabled and the control sends error events instead. If SendErrorEvents is false, the Windows Media Player control displays error dialogs and does not send error events.

Error-handling events supported by the Windows Media Player control include the following:

  • The Error event signals that a critical error has occurred.
  • The Warning event signals that a non-critical event has occurred.

When your application receives an error event, you can determine the specific nature of the error by checking the following properties:

  • HasError property specifies whether the Windows Media Player control currently has an error.
  • ErrorCode property specifies a code number associated with the type of error.
  • ErrorDescription property specifies a description of the error.
  • ErrorCorrection property specifies the type of error correction being used by the Windows Media Player control.


Compact Disc Audio Playback

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control supports playback for Compact Disc (CD) audio. Windows Media Player treats the CD as a single audio stream, with markers at the beginning of each track.

To use CD audio with the embedded Windows Media Player control, you need to set the FileName property to CDAUDIO: (with the trailing ":"). The following example shows how to do this.

<HTML>
<HEAD><TITLE>CD Audio Playback Example</TITLE></HEAD>
<BODY>

<OBJECT ID="MediaPlayer"
    CLASSID="CLSID:22d6f312-b0f6-11d0-94ab-0080c74c7e95"
    WIDTH="320"
    HEIGHT="508"
    STYLE="position:absolute; left:0px; top:70px;"
    >
    <PARAM NAME="FileName" VALUE="cdaudio:">
    <PARAM NAME="AutoStart" VALUE="0">
    <PARAM NAME="ShowControls" VALUE="1">
    <PARAM NAME="ShowStatusBar" VALUE="1">
    <PARAM NAME="ShowDisplay" VALUE="1">
</OBJECT>

</BODY>
</HTML>

Calling the Play method will then start playback of the CD. This does require that a compact disc be present in the computer of the person opening the Web page.

You can specify the playback order, and information about each track, in a Windows Media metafile. Use a separate ENTRY element for each track, and denote tracks by specifying STARTMARKER and ENDMARKER values. For each ENTRY element, set the start marker equal to the marker at the beginning of the track, and set the end marker equal to the marker at the beginning of the next track. For the CD to play all the tracks in sequence, these values must connect together, as shown in the following example Windows Media metafile.

<ASX VERSION="3.0">
    <TITLE>CD Audio with the Media Player</TITLE>
    <AUTHOR>Windows Media Technologies</AUTHOR>
    <COPYRIGHT>(c) 1999, Microsoft, Inc.</COPYRIGHT>

    <ENTRY>
      <TITLE>Track 1: Title 1</TITLE>
      <REF HREF="cdaudio:" />
      <STARTMARKER NUMBER="1"/>
      <ENDMARKER NUMBER="2"/>
   </ENTRY>

    <ENTRY>
      <TITLE>Track 2: Title 2</TITLE>
      <REF HREF="cdaudio:" />
      <STARTMARKER NUMBER="2"/>
      <ENDMARKER NUMBER="3"/>
    </ENTRY>

    <ENTRY>
      <TITLE>Track 3: Title 3</TITLE>
      <REF HREF="cdaudio:" />
      <STARTMARKER NUMBER="3"/>
      <ENDMARKER NUMBER="4"/>
    </ENTRY>

    <ENTRY>
      <TITLE>Track 4: Title 4</TITLE>
      <REF HREF="cdaudio:" />
      <STARTMARKER NUMBER="4"/>
    </ENTRY>
</ASX>

The first track is assigned a STARTMARKER value of 1 and an ENDMARKER value of 2, which stops audio playback when it reaches the second marker in the audio stream. Each of the tracks is chained together in this way until the last track of the CD, for which you should not specify an ENDMARKER.

For information on metafiles, see Windows Media Metafiles. For information on building faceplates for the Windows Media Player control, see the Faceplate Authoring Guide.


Using DVD with the Version 6.4 Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

This section explains how to play DVD-Video through the Windows Media Player control. This section provides an overview of the basics of digital video disc (DVD) and its unique features; defines DVD-specific properties, methods, and event codes; and explains how to play DVD-Video through a Web page.

Note To use DVD playback with the Windows Media Player control, you need to have Microsoft® Internet Explorer 5, the Microsoft® Windows® 98 OEM Service Release (OSR), or Microsoft® Windows® 2000 installed.

This section contains the following articles.

  • DVD Overview
  • Viewing DVD in a Web Page
  • Using DVD Properties
  • Using DVD Methods
  • Using DVD Event Codes
  • DVD Event Codes
  • DVD Error Codes
  • DVD Samples


DVD Overview

This topic applies to Windows Media Player version 6.4 only.

Digital video disc (DVD) represents the next generation in optical disc storage technology for video and audio computer data. Essentially, a DVD is a compact disc (CD) that provides increased storage capacity, faster data access, and superior playback quality. A DVD holds 4.38 gigabytes (4.7 billion bytes) of data on each side — enough for a movie more than two hours long. Each side can hold two layers of information, allowing a single DVD to hold up to 15.9 gigabytes (17 billion bytes) of audio, video, and other types of data. A CD-ROM of the same physical size holds 650 megabytes (682 million bytes) of data.

DVD aims to provide a unified solution for home entertainment, business, computer storage, and computer multimedia with a single digital format. Eventually, DVD aims to replace audio CD, videotape, laser disc, and CD-ROM technologies. Currently, DVD has widespread support from all major electronic companies, all major computer hardware companies, all major movie studios, and many major music studios. Thus, DVD technology has an excellent opportunity to revolutionize the distribution of media.

A DVD title can offer simultaneous multilingual support, parental control mechanisms, menu options, chapter searching, and varied viewing through multiple camera angles.

Note To use DVD playback with the Windows Media Player control, you need to have Microsoft® Internet Explorer 5, the Microsoft® Windows® 98 OEM Service Release (OSR), or Microsoft® Windows® 2000 installed.

This article contains the following sections.

  • DVD Interfaces
  • DVD Control Data Structure
  • DVD Features


DVD Interfaces

This topic applies to Windows Media Player version 6.4 only.

The Microsoft Windows Media Player control exposes the IMediaPlayerDvd interface through the DVD property. This interface enables the Windows Media Player control to access the Microsoft® DirectShow® DVD-specific properties, methods, and events.

DirectShow provides the following DVD-related interfaces.

Interface | Purpose
IDvdGraphBuilder | Enables the DVD application writer to easily build a filter graph for DVD-Video playback.
IDvdControl | Controls the playback and search mechanisms of a DVD-Video disc that contains one or more video movies.
IDvdInfo | Enables an application to query for attributes of available DVD-Video titles and the DVD player status.

For more information on the DirectShow DVD-related interfaces, see Overview of DVD Interfaces and Data Types in the DirectShow Software Development Kit.

Later sections of this article group properties, methods, and events from the IMediaPlayerDvd interface into functional categories. For more information about DVD properties, see Using DVD Properties. For more information about DVD methods, see Using DVD Methods.

The Windows Media Player control also provides a number of event and error codes. For more information about event codes, see Using DVD Event Codes. For more information about error codes, see DVD Error Codes.


DVD Control Data Structure

This topic applies to Windows Media Player version 6.4 only.

DVD-Video content is organized in large chunks, called titles. A title can be further subdivided with predefined access points, called chapters (the technical term is Part_of_Title, or PTT). Each DVD-Video volume can contain up to 99 titles. Each title can have up to 99 or 999 chapters, depending on how the disc is authored. The Windows Media Player control provides seeking capabilities for DVD at three distinct levels, as outlined in Seeking in DVD.

DVD-Video Volume Structure

Control data | Description
Video Title Set (VTS) | Collection of movies. A single volume can contain from 1 to 99 video title sets.
Title | Individual movie. This might be a simple, linear movie, consisting of one program chain, or it might consist of several program chains.
Program Chain (PGC) | Collection of programs (often chapters in a movie). Possible options include different ratings, camera angles, or a different storyline.
Chapter/Part of Title (PTT) | Access point at a cell boundary in a video stream used to create chapter access points. Can delimit scenes or provide optional scenes from which to choose.
Program (PG) | Collection of cells, which typically make up a scene.
Cell Collection of Video Object Units (VOBUs) | The minimum unit of access for branching navigation.
Interleave Unit (ILVU) | Block of one or more VOBUs in a multiangle stream of video that contains video of only one angle.
Video Object Unit (VOBU) | Group of pictures (GOP). Usually half a second of video.
Pack | 2 KB of data, corresponding to a logical sector of the disc, consisting of only one media type (such as video or audio).

The DVD file system is different from a format like CD-ROM, which contains a linear series of tracks not easily customizable by the author. The author of DVD-formatted media files can control track layout and navigation much more precisely. Authors gain this control because the media file itself has many parts and control mechanisms that enable the author to arrange and rearrange the playback order as needed. You can locate a specific portion of a file by time (in hours, minutes, seconds, and frames) or by chapter value.

A media file is made up of a list of program chains (PGCs), each of which is made up of a list of programs, each of which is made up of a list of cells, each of which is made up of a list of video object units (VOBUs), each of which is made up of a list of packs, and each of which is made up of actual MPEG (Moving Picture Experts Group) data. The following graphic illustrates the DVD file system structure.

DVD file system structure


DVD Features

This topic applies to Windows Media Player version 6.4 only.

This section outlines features specific to DVD-Video and lists the Windows Media Player control methods that provide these features. These features include the following:

  • Seeking in DVD
  • Subpicture
  • Multiple Language Support
  • Variable Speed Play
  • Consumer DVD Interactivity
  • Seamless Video Angle Change

Seeking in DVD

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control enables you to seek at several different levels within DVD content. The DVD-Video disc format includes special data for seeking and navigation.

DVD-Video streams consist of .vob files and associated .ifo files that contain information for navigation and data searching, including random access, fast-forward and fast-reverse play, angle switching, and seamless branching. In the case of One_Sequential_PGC_Titles, a time map table enables time-based seeking. For titles not authored in One_Sequential_PGC format, such as those with branching or multiple ratings, time-based seeking is not supported.

In contrast, MPEG-2 files play from the beginning or require access points to be specified as byte offsets into the file to Group of Pictures (GOP) headers. You can access any GOP without prior authoring of entry points, as is required in the case of DVD-Video chapters.

The following table shows the Windows Media Player control DVD-Video methods exposed for seeking at various levels.

Seeking level | Control data | IMediaPlayerDvd Methods
Title Seeks | Video Title Set (VTS), Title, Program Chain (PGC) | TitlePlay
Chapter Seeks | Chapter/Part of Title (PTT), Program (PG) | ChapterPlay (specifying title and chapter number), ChapterSearch (search for a chapter within the same title), PrevPGSearch, TopPGSearch, NextPGSearch
Time Seeks | Interleave Unit (ILVU), Video Object Unit (VOBU) | TimePlay (start playing specified title from specified time), TimeSearch (start playing from specified time within the same title)

Subpicture

This topic applies to Windows Media Player version 6.4 only.

Subpictures are encoded graphics that can be displayed over the top of the video. The subpicture feature is decoded and alpha blended. The data on the alpha channel could be text for closed captioning, buttons to provide a user interface, menus, subtitles, credits, and so on. Each pixel in a subpicture graphic is encoded with 2 bits, allowing only four colors and four levels of transparency per pixel, chosen from palettes of colors and contrast levels.

Properties relating to the subpicture feature include the following:

  • CurrentSubpictureStream
  • SubpictureOn
  • SubpictureStreamsAvailable

The method relating to subpictures is GetSubpictureLanguage.

The event relating to subpictures is EC_DVD_SUBPICTURE_STREAM_CHANGE.

Multiple Language Support

This topic applies to Windows Media Player version 6.4 only.

DVD-Video provides support for up to eight audio tracks to accommodate various languages. DVD-Video also supports text in different languages for statistics related to the DVD title, such as cast, crew, and title. On-screen menus can be displayed in various languages.

Methods relating to language support include the following:

  • GetAudioLanguage
  • GetSubpictureLanguage

Variable Speed Play

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control provides variable speed play, at both faster and slower speeds than normal, through the ForwardScan and BackwardScan methods.

Consumer DVD Interactivity

This topic applies to Windows Media Player version 6.4 only.

Consumers can interact with DVD titles by selecting and activating buttons and displaying menus. Buttons can be selected by clicking directly on the video window.

Methods relating to consumer interactivity include the following:

  • MenuCall
  • UpperButtonSelect
  • LowerButtonSelect
  • LeftButtonSelect
  • RightButtonSelect
  • ButtonActivate
  • ButtonSelectAndActivate

A mouse rollover causes a select, but is prevented from performing a select and activate action. A mouse click is required to activate the button because mouse movement on a PC differs from remote control tabbing on a consumer player.

Seamless Video Angle Change

This topic applies to Windows Media Player version 6.4 only.

DVD-Video supports up to nine camera angles. These angles can be completely independent video streams or different camera angles of the same scene. The fast seeking of the DVD disc enables you to switch angles seamlessly.

Properties relating to video angles include the following:

  • AnglesAvailable
  • CurrentAngle

Events relating to video angles include the following:

  • EC_DVD_ANGLE_CHANGE
  • EC_DVD_ANGLES_AVAILABLE


Viewing DVD in a Web Page

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control uses automation to expose the DVD-Video–specific interfaces, methods, events, and properties of the Microsoft® DirectShow® Application Programming Interface (API). As a Microsoft® ActiveX® control, the Windows Media Player control can be used as a component in a Web page. Enhanced with digital video disc (DVD) playback capability, the Windows Media Player control adds exciting dynamic content to previously static Web pages.

You can view a Microsoft® Visual Basic® Scripting Edition (VBScript) sample page demonstrating DVD playback in a Web page that builds upon the concepts introduced in this article. The sample is located in the SimpleDVD directory that was installed with the SDK. To view this sample, your system must be capable of DVD-Video playback and have the Microsoft DirectShow drivers installed.

This article contains the following sections.

  • Customizing the Control for DVD Playback
  • Creating a DVD-Enabled Web Page


Customizing the Control for DVD Playback

This topic applies to Windows Media Player version 6.4 only.

By using a scripting language, such as VBScript or Microsoft® JScript®, it is easy to place the Windows Media Player control in an HTML file. This section contains the following topics, which explain how to embed the Windows Media Player control into an HTML page, how to enable the Windows Media Player control to play back DVD, and how to use VBScript routines to manipulate it.

  • Inserting the Windows Media Player Control
  • Setting Control Properties with the PARAM Tag
  • Adding a Simple User Interface
  • Adding the Scripting Code

Inserting the Windows Media Player Control

This topic applies to Windows Media Player version 6.4 only.

The OBJECT tag is used to embed ActiveX objects, such as the Windows Media Player control, into an HTML page. The following code is an example of using the OBJECT tag to insert the Windows Media Player control.

<OBJECT CLASSID="CLSID:22D6F312-B0F6-11D0-94AB-0080C74C7E95" WIDTH="652"
    HEIGHT="382" ID="MediaPlayer1">
</OBJECT>

The following OBJECT tag attributes are required.

  • ID — Name used to reference this instance of the control.
  • CLSID — Class Identifier (CLSID) of the Windows Media Player control. A CLSID is a Component Object Model (COM) object identifier.

Setting Control Properties with the PARAM Tag

This topic applies to Windows Media Player version 6.4 only.

One option for setting the properties of a control in a Web page is adding PARAM tags between the OBJECT tags. This is an ideal way to set design time properties. The following code is an example of the OBJECT tag with PARAM tags added.

<OBJECT CLASSID="CLSID:22D6F312-B0F6-11D0-94AB-0080C74C7E95"
    WIDTH="652"
    HEIGHT="382" ID="MediaPlayer1">
<PARAM NAME="AutoStart" VALUE="0">
<PARAM NAME="Filename" VALUE="DVD:">
<PARAM NAME="ShowControls" VALUE="0">
</OBJECT>

The PARAM tags used in the preceding example have two attributes; the first is the name of the property being set, and the second specifies the value of the property. In the preceding example, the first PARAM tag sets the AutoStart property to false. The remaining PARAM tags change the default values of the FileName property to DVD: and the ShowControls property to false. Note that none of the DVD-specific properties can be set by using the PARAM tag.

It is critical to note that DVD playback is triggered by setting the FileName property to DVD:, which instructs the Windows Media Player control to search for the DVD drive on the local system. If the AutoStart property is set to true (the default value), the Windows Media Player control will then begin DVD playback; otherwise, an event must be associated with DVD playback, such as the selection of a button.

Adding a Simple User Interface

This topic applies to Windows Media Player version 6.4 only.

You can create a simple user interface by adding two groups of button controls to the body of your HTML page, one to control menu selection and one to control the DVD playback state.

The following code creates the button controls to handle the selection of menu items from the DVD menu screen.

<INPUT TYPE="BUTTON" STYLE="WIDTH:70" NAME="cmdTopSelect" VALUE="Top">
<INPUT TYPE="BUTTON" STYLE="WIDTH:70" NAME="cmdLeftSelect" VALUE="Left">
<INPUT TYPE="BUTTON" STYLE="WIDTH:70" NAME="cmdRightSelect" VALUE="Right">
<INPUT TYPE="BUTTON" STYLE="WIDTH:70" NAME="cmdBottomSelect" VALUE="Bottom">
<INPUT TYPE="BUTTON" STYLE="WIDTH:70" NAME="cmdButtonActivate" VALUE="Select">

The following code creates the button controls that will handle basic playback (play, pause, and stop), as well as chapter searching and scanning.

<INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdPlay" VALUE="Play">
<INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdPause" VALUE="Pause">
<INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdStop" VALUE="Stop">
<INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdResume" VALUE="Resume">
<INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdShowMenu" VALUE="Menu">
<INPUT TYPE="BUTTON" NAME="cmdPrevChapter" VALUE="|<<">
<INPUT TYPE="BUTTON" NAME="cmdRewind" VALUE="<<">
<INPUT TYPE="BUTTON" NAME="cmdFastForward" VALUE=">>">
<INPUT TYPE="BUTTON" NAME="cmdNextChapter" VALUE=">>|">

Adding the Scripting Code

This topic applies to Windows Media Player version 6.4 only.

Scripting code adds interactivity to your page, enabling you to programmatically respond to events, to call methods, and to change run-time properties.

First, you must notify the browser which scripting language you are authoring with by using the HTML SCRIPT tag. Include your script commands within HTML comment tags so browsers that do not support scripting do not render your code as text. Put the SCRIPT tag anywhere within the BODY of your HTML file and embed the comment-surrounded code within the opening and closing SCRIPT tags.

The following code demonstrates how each subroutine is attached to the OnClick event of a specific button that was previously defined. When an event is triggered by a button being clicked, the code makes a call (or series of calls) to the Windows Media Player control, specifying the action to be taken.

<SCRIPT LANGUAGE="VBScript">
<!--
Dim isScanning

isScanning = False

Sub cmdPlay_OnClick()
    If isScanning Then
        MediaPlayer1.DVD.ForwardScan(1)
    Else
        MediaPlayer1.Play()
    End If

    isScanning = False
End Sub

Sub cmdPause_OnClick()
    MediaPlayer1.Pause()
End Sub

Sub cmdStop_OnClick()
    MediaPlayer1.Stop()
End Sub

Sub cmdResume_OnClick()
    MediaPlayer1.DVD.ResumeFromMenu()
End Sub

Sub cmdShowMenu_OnClick()
    MediaPlayer1.DVD.MenuCall(3)
End Sub

Sub cmdPrevChapter_OnClick()
    MediaPlayer1.DVD.PrevPGSearch()
End Sub

Sub cmdNextChapter_OnClick()
    MediaPlayer1.DVD.NextPGSearch()
End Sub

Sub cmdFastForward_OnClick()
    isScanning = True
    MediaPlayer1.DVD.ForwardScan(5)
End Sub

Sub cmdRewind_OnClick()
    isScanning = True
    MediaPlayer1.DVD.BackwardScan(5)
End Sub

Sub cmdTopSelect_OnClick()
    MediaPlayer1.DVD.UpperButtonSelect()
End Sub

Sub cmdLeftSelect_OnClick()
    MediaPlayer1.DVD.LeftButtonSelect()
End Sub

Sub cmdRightSelect_OnClick()
    MediaPlayer1.DVD.RightButtonSelect()
End Sub

Sub cmdBottomSelect_OnClick()
    MediaPlayer1.DVD.LowerButtonSelect()
End Sub

Sub cmdButtonActivate_OnClick()
    Dim buttonNumber
    buttonNumber = MediaPlayer1.DVD.CurrentButton
    MediaPlayer1.DVD.ButtonSelectAndActivate(buttonNumber)
End Sub

-->
</SCRIPT>


Creating a DVD-Enabled Web Page

This topic applies to Windows Media Player version 6.4 only.

By combining the elements previously discussed in this article, you can see how the pieces fit together in the following sample code.

Try the following sample code to showcase the Windows Media Player control's capabilities on a system with DVD-Video capabilities. Copy and paste the code into a text file and save it with the .htm extension.

<HTML>
 <HEAD>
 <TITLE>DVD_Demo</TITLE>
 </HEAD>
 <BODY BGCOLOR="#000000" TEXT="#00FFFF">

 <CENTER>
 <TABLE>
 <TR>
 <TD VALIGN="TOP" WIDTH="10%">
 </TD>
 <TD>
 <P ALIGN="center">
 <OBJECT
    CLASSID="clsid:22D6F312-B0F6-11D0-94AB-0080C74C7E95"
    WIDTH="652"
    HEIGHT="382"
    ID="MediaPlayer1">
 <PARAM NAME="AutoStart" value="0">
 <PARAM NAME="Filename" value="DVD:">
 <PARAM NAME="ShowControls" value="0">
 </OBJECT>
 </P>
 </TD>
 <TD VALIGN="TOP" WIDTH="10%">
Menu Select
 <BR>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:70"
        NAME="cmdTopSelect" VALUE="Top">
 <BR>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:70"
        NAME="cmdLeftSelect" VALUE="Left">
 <BR>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:70"
        NAME="cmdRightSelect" VALUE="Right">
 <BR>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:70"
        NAME="cmdBottomSelect" VALUE="Bottom">
 <P>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:70"
        NAME="cmdButtonActivate" VALUE="Select">
 <P>
 </TD>
 </TR>
 </TABLE>
 </CENTER>

 <CENTER>
 <INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdPlay" VALUE="Play">
 <INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdPause" VALUE="Pause">
 <INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdStop" VALUE="Stop">
 <INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdResume" VALUE="Resume">
 <INPUT TYPE="BUTTON" STYLE="WIDTH:60" NAME="cmdShowMenu" VALUE="Menu">
 <P>
 <INPUT TYPE="BUTTON" NAME="cmdPrevChapter" VALUE="| < <">
 <INPUT TYPE="BUTTON" NAME="cmdRewind" VALUE=" < <">
 <INPUT TYPE="BUTTON" NAME="cmdFastForward" VALUE=" > >">
 <INPUT TYPE="BUTTON" NAME="cmdNextChapter" VALUE=" > >|">
 </CENTER>

 <SCRIPT LANGUAGE="VBScript">
 <!--
 Dim isScanning

isScanning = False

Sub cmdPlay_OnClick()
    If isScanning Then
        MediaPlayer1.DVD.ForwardScan(1)
    Else
        MediaPlayer1.Play()
    End If

    isScanning = False
End Sub

Sub cmdPause_OnClick()
    MediaPlayer1.Pause()
End Sub

Sub cmdStop_OnClick()
    MediaPlayer1.Stop()
End Sub

Sub cmdResume_OnClick()
    MediaPlayer1.DVD.ResumeFromMenu()
End Sub

Sub cmdShowMenu_OnClick()
    MediaPlayer1.DVD.MenuCall(3)
End Sub

Sub cmdPrevChapter_OnClick()
    MediaPlayer1.DVD.PrevPGSearch()
End Sub

Sub cmdNextChapter_OnClick()
    MediaPlayer1.DVD.NextPGSearch()
End Sub

Sub cmdFastForward_OnClick()
    isScanning = True
    MediaPlayer1.DVD.ForwardScan(5)
End Sub

Sub cmdRewind_OnClick()
    isScanning = True
    MediaPlayer1.DVD.BackwardScan(5)
End Sub

Sub cmdTopSelect_OnClick()
    MediaPlayer1.DVD.UpperButtonSelect()
End Sub

Sub cmdLeftSelect_OnClick()
    MediaPlayer1.DVD.LeftButtonSelect()
End Sub

Sub cmdRightSelect_OnClick()
    MediaPlayer1.DVD.RightButtonSelect()
End Sub

Sub cmdBottomSelect_OnClick()
    MediaPlayer1.DVD.LowerButtonSelect()
End Sub

Sub cmdButtonActivate_OnClick()
    Dim buttonNumber
    buttonNumber = MediaPlayer1.DVD.CurrentButton
    MediaPlayer1.DVD.ButtonSelectAndActivate(buttonNumber)
End Sub
  -->
 </SCRIPT>
 </BODY>
</HTML>


Using DVD Properties

This topic applies to Windows Media Player version 6.4 only.

DVD-specific properties are called on the Windows Media Player control DVD property, which then resolves to a MediaPlayer object, as indicated in the following syntax.

MediaPlayer.DVD.AnglesAvailable

DVD properties enable you to retrieve or set various DVD elements, such as audio streams, a subpicture stream, and video angles.

The Windows Media Player control supports the following DVD properties. For more information, see Properties in the Version 6.4 Control Reference section.

  • AnglesAvailable
  • AudioStreamsAvailable
  • ButtonsAvailable
  • CCActive
  • ColorKey
  • CurrentAngle
  • CurrentAudioStream
  • CurrentButton
  • CurrentCCService
  • CurrentChapter
  • CurrentDiscSide
  • CurrentDomain
  • CurrentSubpictureStream
  • CurrentTime
  • CurrentTitle
  • CurrentVolume
  • FramesPerSecond
  • Root
  • SubpictureOn
  • SubpictureStreamsAvailable
  • TitlesAvailable
  • TotalTitleTime
  • UniqueID
  • VolumesAvailable


Using DVD Methods

This topic applies to Windows Media Player version 6.4 only.

DVD-specific methods are called on the Windows Media Player control's DVD property, which then resolves to a MediaPlayer object, as indicated in the following syntax.

MediaPlayer.DVD.ChapterPlay( Title, Chapter )

For standard playback functionality (pause, play, and stop), DVD-specific methods have not been created. Use the following Windows Media Player control methods.

  • Pause
  • Play
  • Stop

In most cases, the standard Windows Media Player control Pause, Play, and Stop methods function correctly. However, when toggling between Play and the digital video disc (DVD) methods BackwardScan and ForwardScan, the methods will not interact. To correctly implement these methods in tandem, add a flag to track whether your application is scanning through the DVD when the Play method is called.

For example, the following code uses a flag called isScanning to determine whether the DVD is being scanned. If it is, ForwardScan is called with a parameter of 1 to reduce the scanning speed to standard playing speed; otherwise, the Play method is called.

Dim isScanning

isScanning = False

Sub cmdPlay_OnClick()
    If isScanning Then
        MediaPlayer1.DVD.ForwardScan(1)
    Else
        MediaPlayer1.Play()
    End If

    isScanning = False
End Sub

'Call this when you want to fast forward through the DVD
Sub cmdFastForward_OnClick()
    isScanning = True
    MediaPlayer1.DVD.ForwardScan(5)
End Sub

'Call this when you want to rewind through the DVD
Sub cmdRewind_OnClick()
    isScanning = True
    MediaPlayer1.DVD.BackwardScan(5)
End Sub

Note Using the Stop method is not recommended, because it discontinues DVD playback. To continue DVD playback, you must restart the video from the beginning by calling the Play method or refreshing the page. To avoid this, use the Pause method to stop the video and the Play method to resume the video.

The Windows Media Player control supports the following DVD methods. For more information, see Methods in the Version 6.4 Control Reference section.

  • BackwardScan
  • ButtonActivate
  • ButtonSelectAndActivate
  • ChapterPlay
  • ChapterPlayAutoStop
  • ChapterSearch
  • ForwardScan
  • GetAllGPRMs
  • GetAllSPRMs
  • GetAudioLanguage
  • GetNumberOfChapters
  • GetSubpictureLanguage
  • GoUp
  • LeftButtonSelect
  • LowerButtonSelect
  • MenuCall
  • NextPGSearch
  • PrevPGSearch
  • ResumeFromMenu
  • RightButtonSelect
  • StillOff
  • TimePlay
  • TimeSearch
  • TitlePlay
  • TopPGSearch
  • UOPValid
  • UpperButtonSelect


Using DVD Event Codes

This topic applies to Windows Media Player version 6.4 only.

An event code is code that executes when an event occurs. An event is an action, recognized by the DVD object, for which you can write code to respond. Events can be generated by a user action, such as clicking the mouse or pressing a key on the keyboard. Events are also generated by the system itself, for example, in the case of timers.

DVD-specific events are returned to the Windows Media Player control through the DVDNotify event in the following form.

MediaPlayer_DVDNotify(Event, Param1, Param2)

The following subroutine shows a way to capture the DVD event codes in Microsoft® Visual Basic® Scripting Edition (VBScript). Note that the DVD event codes should be referred to by a constant integer value, ranging from 257 to 272, 274, or 275. To illustrate how the DVD event codes work, use the DIV tag to create two sections that will display the current event code and the values of its parameter list.

<TABLE>
<TR>
<TD><DIV ID=codeConstant> </DIV></TD>
<TD><DIV ID=paramList> </DIV></TD>
</TR>
<TABLE>

After enumerating the event codes, the following code shows you how to display the events and the values of their parameters as they are returned to the Windows Media Player control.

strEventCode = szDVDEventCode(eventOffset)
codeConstant.innertext = "DVDNotify EventCode = " + CStr(EventCode) + _
" = " + strEventCode
paramList.innertext  = "Param1 = " + CStr(Param1) + "  Param2 = " + _
CStr(Param2)

Here is the complete example, showing the necessary variables, the enumeration of the event codes, and the displaying of the incoming event codes and parameters.

Sub MediaPlayer1_DVDNotify(EventCode, Param1, Param2)

Dim strEventCode
Dim strParam1
Dim szDVDEventCode(20)
Dim eventOffset

eventOffset = EventCode - 257

szDVDEventCode(0)  = " (EC_DVD_DOMAIN_CHANGE)"
szDVDEventCode(1)  = " (EC_DVD_TITLE_CHANGE)"
szDVDEventCode(2)  = " (EC_DVD_CHAPTER_START)"
szDVDEventCode(3)  = " (EC_DVD_AUDIO_STREAM_CHANGE)"
szDVDEventCode(4)  = " (EC_DVD_SUBPICTURE_STREAM_CHANGE)"
szDVDEventCode(5)  = " (EC_DVD_ANGLE_CHANGE)"
szDVDEventCode(6)  = " (EC_DVD_BUTTON_CHANGE)"
szDVDEventCode(7)  = " (EC_DVD_VALID_UOPS_CHANGE)"
szDVDEventCode(8)  = " (EC_DVD_STILL_ON)"
szDVDEventCode(9)  = " (EC_DVD_STILL_OFF)"
szDVDEventCode(10) = " (EC_DVD_CURRENT_TIME)"
szDVDEventCode(11) = " (EC_DVD_ERROR)"
szDVDEventCode(12) = " (EC_DVD_WARNING)"
szDVDEventCode(13) = " (EC_DVD_CHAPTER_AUTOSTOP)"
szDVDEventCode(14) = " (EC_DVD_NO_FP_PGC)"
szDVDEventCode(15) = " (EC_DVD_PLAYBACK_RATE_CHANGE)"
szDVDEventCode(17) = " (EC_DVD_PLAYBACK_STOPPED)"
szDVDEventCode(18) = " (EC_DVD_ANGLES_AVAILABLE)"

strEventCode = szDVDEventCode(eventOffset)
codeConstant.innertext = "DVDNotify EventCode = " + _
    CStr(EventCode) + " = " + strEventCode
paramList.innertext  = "Param1 = " + CStr(Param1) + _
    "  Param2 = " + CStr(Param2)
End Sub

A more typical use of event codes would be to capture the current time of the DVD, allowing the current time to be displayed on the page. For example, the following code uses a DIV tag to set aside a separate, distinct section to hold the current time value.

<DIV ID=timeshow> </DIV>

Then, add the DVDNotify event to your subroutine list, as shown in the following:

Sub MediaPlayer1_DVDNotify(EventCode, Param1, Param2 )
  If EventCode = 267 Then    'EC_DVD_CURRENT_TIME = 267
    timeshow.innertext = Left(MediaPlayer1.DVD.CurrentTime, 8)
  End If
End Sub

Now, when an EC_DVD_CURRENT_TIME event occurs, the value for the current time will be placed in the timeshow DIV. Use the VBScript Left function to extract the eight left-most characters from the string containing the current time value.

The Windows Media Player control supports the following DVD event codes. For more information, see DVD Event Codes.

  • EC_DVD_ANGLE_CHANGE
  • EC_DVD_ANGLES_AVAILABLE
  • EC_DVD_AUDIO_STREAM_CHANGE
  • EC_DVD_BUTTON_CHANGE
  • EC_DVD_CHAPTER_AUTOSTOP
  • EC_DVD_CHAPTER_START
  • EC_DVD_CURRENT_TIME
  • EC_DVD_DOMAIN_CHANGE
  • EC_DVD_ERROR
  • EC_DVD_NO_FP_PGC
  • EC_DVD_PLAYBACK_RATE_CHANGE
  • EC_DVD_PLAYBACK_STOPPED
  • EC_DVD_STILL_OFF
  • EC_DVD_STILL_ON
  • EC_DVD_SUBPICTURE_STREAM_CHANGE
  • EC_DVD_TITLE_CHANGE
  • EC_DVD_VALID_UOPS_CHANGE
  • EC_DVD_WARNING


DVD Event Codes

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control supports the following digital video disc (DVD) event notification codes.

DVD Event Notification Code | Value | Description
EC_DVD_ANGLE_CHANGE | 262 | Signals that either the number of available angles has changed, or the current user angle number has changed.
EC_DVD_ANGLES_AVAILABLE | 275 | Occurs when an angle block is being played and angle changes can be performed.
EC_DVD_AUDIO_STREAM_CHANGE | 260 | Signals that the current user audio stream number has changed for the main title.
EC_DVD_BUTTON_CHANGE | 263 | Signals that either the number of available buttons has changed, or the currently selected button number has changed.
EC_DVD_CHAPTER_AUTOSTOP | 270 | Indicates that playback has stopped as the result of a call to the ChapterPlayAutoStop method.
EC_DVD_CHAPTER_START | 259 | Signals that the DVD player has started playback of a new program in the TT_DOM domain.
EC_DVD_CURRENT_TIME | 267 | Signals the beginning of each video object unit (VOBU), which occurs every 0.4 to 1.0 seconds.
EC_DVD_DOMAIN_CHANGE | 257 | Indicates the DVD player's new domain.
EC_DVD_ERROR | 268 | Signals a DVD error condition.
EC_DVD_NO_FP_PGC | 271 | Signals that the DVD does not have a First Play Program Chain (FP_PGC) and that the DVD Navigator will not automatically load any program chain (PGC) or start playback.
EC_DVD_PLAYBACK_RATE_CHANGE | 272 | Signals that a rate change in the playback has been initiated.
EC_DVD_PLAYBACK_STOPPED | 274 | Indicates that playback has been stopped. The DVD Navigator has completed playback of the program chain (PGC) and did not find any other branching instruction for subsequent playback.
EC_DVD_STILL_OFF | 266 | Signals the end of any still (PGC, Cell, or VOBU).
EC_DVD_STILL_ON | 265 | Signals the beginning of any still (PGC, Cell, or VOBU).
EC_DVD_SUBPICTURE_STREAM_CHANGE | 261 | Signals that the current user subpicture stream number has changed for the main title.
EC_DVD_TITLE_CHANGE | 258 | Occurs when the current title number changes.
EC_DVD_VALID_UOPS_CHANGE | 264 | Signals that the available set of IDvdControl interface methods has changed.
EC_DVD_WARNING | 269 | Signals a DVD warning condition.


Player6.EC_DVD_ANGLE_CHANGE

Signals that either the number of available angles has changed, or the current user angle number has changed.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 262 if this event occurs.

Param1

DWORD value indicating the number of available angles. If the value is 1, the current video does not contain multiple angles.

Param2

DWORD value indicating the current user angle number.

Remarks

Angle numbers range from 1 to 9.

The current angle number can change automatically with a navigation command authored on the disc, as well as through application control by using the CurrentAngle property.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_ANGLES_AVAILABLE

Occurs when an angle block is being played and angle changes can be performed.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 275 if this event occurs.

Param1

Boolean value indicating whether an angle block is being played. If true, an angle block is being played and angle changes can be performed. Otherwise, playback is not in an angle block and angles are not available.

Param2

Zero.

Remarks

Angle changes are not restricted to angle blocks, but the manifestation of the angle change can be seen only in an angle block.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_AUDIO_STREAM_CHANGE

Signals that the current user audio stream number has changed for the main title.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 260 if this event occurs.

Param1

DWORD value indicating the new user audio stream number. Audio stream numbers range from 0 to 7. A value of 0xFFFFFFFF indicates that no stream is selected.

Param2

Zero.

Remarks

The current user audio stream can change automatically with a navigation command authored on the disc, as well as through application control by using the CurrentAudioStream property.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_BUTTON_CHANGE

Signals that either the number of available buttons has changed, or the currently selected button number has changed.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 263 if this event occurs.

Param1

DWORD value indicating the number of available buttons.

Param2

DWORD value indicating the currently selected button number. A value of zero indicates that no button is selected.

Remarks

Button numbers range from 1 to 36.

The currently selected button can change automatically with a navigation command authored on the disc as well as through application control by using the properties and methods that effect button selection.

This event can signal any of the available button numbers. These numbers do not always correspond to button numbers used for the ButtonSelectAndActivate method, because that method can activate only a subset of buttons.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_CHAPTER_AUTOSTOP

Indicates that playback has stopped as the result of a call to the ChapterPlayAutoStop method.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 270 if this event occurs.

Param1

Zero.

Param2

Zero.

Remarks

The TT_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.

See Also

  • Player6.ChapterPlayAutoStop


Player6.EC_DVD_CHAPTER_START

Signals that the DVD player has started playback of a new program in the TT_DOM domain.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 259 if this event occurs.

Param1

DWORD value indicating the new chapter number.

Param2

Zero.

Remarks

Only simple linear movies signal this event.

The TT_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_CURRENT_TIME

Signals the beginning of each video object unit (VOBU), which occurs every 0.4 to 1.0 seconds.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 267 if this event occurs.

Param1

ULONG value indicating the current playback timecode in a binary coded decimal (BCD) hours, minutes, seconds, frames (hh:mm:ss:ff) format.

Param2

ULONG value indicating the frame rate. Zero indicates 25 frames per second while 1 indicates 30 frames per second (assuming no frames are dropped). A value of 2 indicates that the playback time cannot be determined.

Remarks

Only simple linear movies signal this event.

The TT_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_DOMAIN_CHANGE

Indicates the digital video disc (DVD) player's new domain.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 257 if this event occurs.

Param1

DWORD value indicating the new domain. It can have one of the following possible values.

Value | Constant | Domain | Description
1 | FP_DOM | FirstPlay | Doing default initialization of a DVD disc.
2 | VMGM_DOM | VideoManagerMenu | Displaying menus for whole disc.
3 | VTSM_DOM | VideoTitleSetMenu | Displaying menus for current title set.
4 | TT_DOM | Title | Displaying current title.
5 | STOP_DOM | Stop | Player is in stopped state.

Param2

Zero.

Remarks

The DVD player signals this event whenever it changes domains. The domain indicates the state of the DVD player.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_ERROR

Signals a digital video disc (DVD) error condition.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 268 if this event occurs.

Param1

DWORD value indicating the error condition. It can have one of the following possible values.

Value | Error Condition
1 | Unexpected. Something unexpected happened; perhaps content is incorrectly authored. Playback is stopped.
2 | Copy Protect Fail. Key exchange for DVD copy protection failed. Playback is stopped.
3 | Invalid DVD 1.0 Disc. DVD disc is incorrectly authored for v1.0. Playback is stopped.
4 | Invalid Disc Region. The disc cannot be played because it is not authored to play in the system region. Possibly the region mismatch can be fixed by changing the system region with dvdrgn.exe.
6 | Macrovision Fail. Macrovision distribution failed. Playback is stopped.
7 | Incompatible System and Decoder Regions. No discs can be played because the system region does not match the decoder region.
8 | Incompatible Disc And Decoder Regions. The disc cannot be played because the disc is not authored to be played in the decoder's region.

Param2

Zero.

Remarks

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.

See Also

  • DVD Error Codes


Player6.EC_DVD_NO_FP_PGC

Signals that the digital video disc (DVD) does not have a First Play Program Chain (FP_PGC) and that the DVD Navigator will not automatically load any program chain (PGC) or start playback.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 271 if this event occurs.

Param1

Zero.

Param2

Zero.

Remarks

The FP_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_PLAYBACK_RATE_CHANGE

Signals that a rate change in the playback has been initiated.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 272 if this event occurs.

Param1

LONG value indicating the new playback rate. The value is the actual playback rate multiplied by 10,000. A value less than zero indicates reverse playback mode. A value greater than zero indicates forward playback mode.

Param2

Zero.

Remarks

The TT_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_PLAYBACK_STOPPED

Indicates that playback has been stopped. The DVD Navigator has completed playback of the program chain (PGC) and did not find any other branching instruction for subsequent playback.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 274 if this event occurs.

Param1

Zero.

Param2

Zero.

Remarks

All domains raise this event. For more information on domains, see the CurrentDomain property.

This event occurs only on completion of the playback of the PGC, not after a user-initiated stop.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_STILL_OFF

Signals the end of any still (PGC, Cell, or VOBU).

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 266 if this event occurs.

Param1

Zero.

Param2

Zero.

Remarks

This event indicates that any currently active still has been released.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_STILL_ON

Signals the beginning of any still (PGC, Cell, or VOBU).

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 265 if this event occurs.

Param1

Boolean value indicating whether buttons are available. False indicates that buttons are available; therefore, the StillOff method will not work. True indicates that no buttons are available and StillOff will work.

Param2

DWORD value indicating the number of seconds the still will last. The value 0xFFFFFFFF indicates an infinite still, which means the player will wait until the user presses a button or the application calls StillOff.

Remarks

All combinations of buttons and still are possible (buttons on with still on, buttons on with still off, button off with still on, button off with still off).

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_SUBPICTURE_STREAM_CHANGE

Signals that the current user subpicture stream number has changed for the main title.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 261 if this event occurs.

Param1

DWORD value indicating the new user subpicture stream number. Subpicture stream numbers range from 0 to 31. The value 0xFFFFFFFF indicates that no stream is selected.

Param2

Zero.

Remarks

Subpictures are encoded graphics, such as subtitles or menus, that can be displayed over the top of the video.

The subpicture can change automatically with a navigation command authored on disc, as well as through application control by using the CurrentSubpictureStream property.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.

See Also

  • Player6.CurrentSubpictureStream
  • Player6.SubpictureOn
  • Player6.SubpictureStreamsAvailable
  • Player6.GetSubpictureLanguage


Player6.EC_DVD_TITLE_CHANGE

Occurs when the current title number changes.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 258 if this event occurs.

Param1

DWORD value indicating the new title number.

Param2

Zero.

Remarks

Title numbers range from 1 to 99. This number indicates the Title Track Number (TTN), which is the title number with respect to the whole disc, not the Title Set_Title Track Number (VTS_TTN), which is the title number with respect to just a current Video Title Set (VTS).

The TT_DOM domain raises this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_VALID_UOPS_CHANGE

Signals that the available set of DVD methods has changed.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 264 if this event occurs.

Param1

DWORD value containing bits for all user operations, indicating which commands the digital video disc (DVD) explicitly disabled. Each bit in the DWORD represents the state (valid or not valid) of a user operation. If the bit corresponding to a user operation is set, then that user operation is not valid. For more information, see Remarks.

Param2

Zero.

Remarks

The value of Param1 is a bit field defined as follows:

Bit | User function
0 | TimePlay, TimeSearch
1 | ChapterPlay, ChapterSearch
2 | TitlePlay
3 | Stop
4 | GoUp in TT_DOM domain, GoUp in Menu-space domain
5 | TimeSearch, ChapterSearch
6 | PrevPGSearch, TopPGSearch
7 | NextPGSearch
8 | ForwardScan
9 | BackwardScan
10 | MenuCall with a parameter value of 2 (Title Menu)
11 | MenuCall with a parameter value of 3 (Root Menu)
12 | MenuCall with a parameter value of 4 (Sub-picture Menu)
13 | MenuCall with a parameter value of 5 (Audio Menu)
14 | MenuCall with a parameter value of 6 (Angle Menu)
15 | MenuCall with a parameter value of 7 (Chapter Menu)
16 | ResumeFromMenu
17 | UpperButtonSelect, LowerButtonSelect, LeftButtonSelect, RightButtonSelect, ButtonActivate, ButtonSelectAndActivate
18 | StillOff
19 | Pause
20 | EC_DVD_AUDIO_STREAM_CHANGE
21 | EC_DVD_SUBPICTURE_STREAM_CHANGE
22 | EC_DVD_ANGLE_CHANGE

This event indicates only which operations are explicitly disabled by the content on the DVD disc, and does not guarantee that it is valid to call methods that are not disabled. For example, if no buttons are present, the ButtonActivate method won't work, even if the method is not explicitly disabled.

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


Player6.EC_DVD_WARNING

Signals a digital video disc (DVD) warning condition.

Syntax

MediaPlayer_DVDNotify(Event, Param1, Param2)

Parameters

Event

Value that resolves to 269 if this event occurs.

Param1

DWORD value indicating the warning condition. It can have one of the following possible values.

Value | Warning Condition
1 | Invalid DVD 1.0 Disc. DVD disc is incorrectly authored. Playback can continue, but unexpected behavior may occur.
2 | Format Not Supported. A decoder would not support the current format. Playback of a stream (audio, video, or sub-picture) may not function.
3 | Illegal Nav Command. The internal DVD navigation command processor attempted to process an illegal command, or something unexpected happened (perhaps content is incorrectly authored). Playback is stopped.

Param2

Zero.

Remarks

All domains raise this event. For more information on domains, see the CurrentDomain property.

For information on how to use this event code, see DVDNotify.


DVD Error Codes

This topic applies to Windows Media Player version 6.4 only.

The following table lists the digital video disc (DVD) error codes, their friendly strings, and hexadecimal values.

Error code | Friendly string | Hexadecimal value
VFW_E_DVD_OPERATION_INHIBITED | "This User Operation is inhibited by DVD Content at this time." | 0x80040276
VFW_E_DVD_INVALIDDOMAIN | "This Operation is not permitted in the current domain." | 0x80040277
VFW_E_DVD_NO_BUTTON | "Requested Button is not available." | 0x80040278
VFW_E_DVD_GRAPHNOTREADY | "DVD-Video playback graph has not been built yet." | 0x80040279
VFW_E_DVD_RENDERFAIL | "DVD-Video playback graph building failed." | 0x8004027A
VFW_E_DVD_DECNOTENOUGH | "DVD-Video playback graph could not be built due to insufficient decoders." | 0x8004027B


DVD Windows Media Player Control Samples

This topic applies to Windows Media Player version 6.4 only.

The following samples demonstrate DVD-Video playback through the Windows Media Player control. They are available in the Samples directory that was installed with the SDK.

Important To view these samples, your system must be capable of DVD-Video playback and have the Microsoft® DirectShow® drivers installed.

Sample | Description
Simple DVD-Enabled Web Page | This sample features DVD-Video playback through an embedded Windows Media Player control, using DVD playback methods and a simple user interface (UI).
Advanced DVD User-Interface Design | This sample features DVD-Video playback through an embedded Windows Media Player control. A customized graphical user interface (GUI) is linked to scripting functions that control the DVD playback.
DVD Overlay | This sample demonstrates the potential of integrating 3-D content with DVD playback using a scripting language and the framework provided by Microsoft Internet Explorer 5, the Microsoft Windows Media Player control, and Microsoft DirectAnimation™.


Faceplate Authoring Guide

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player is a versatile tool for presenting local and streaming multimedia files. It supports nearly all of the major media file formats, including Windows Media™ files (files that have an .avi, .asf, .wmv, or .wma file name extension), and audio formats such as MP3, MIDI, and compact disc. Recognizing the importance of multimedia to Web content, Microsoft created the Windows Media Player control. This technology enables Windows Media Player to exist as a Microsoft® ActiveX® control inside a Web page along with other content.

Microsoft has continued to enhance the Windows Media Player control. All the functionality of the Windows Media Player is now exposed to Web scripting languages such as Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft® JScript®. Using dynamic HTML (DHTML), you can build a custom user interface (often called a faceplate) to the Windows Media Player control. A faceplate can be tailored to the design of your Web page or to the media content that you present. It can also display information contained in a playlist, such as artist, track title, and copyright information, as well as links to relevant Web sites or online stores.

The user interface elements built in to Windows Media Player (such as the buttons and the display panel) are available for any faceplate to use, but they can be completely disabled and replaced with graphical buttons and scripts that you create. For complete control, you can install the Windows Media Player control as an HTML application. This technology is introduced by Microsoft® Internet Explorer 5 and gives you control over the browser window that displays the faceplate.

Creating faceplates for the Windows Media Player control requires some basic knowledge of Web scripting and DHTML. The more you know about each, the more interactive and impressive your faceplate can be. The articles in this section provide the background information you need to start creating faceplates and introduce the basics of writing scripts that access the Windows Media Player control.

The information on authoring faceplates is presented in the following articles.

  • Creating an HTML Application Faceplate
  • Controlling the Windows Media Player from Scripts
  • Faceplate Layout in DHTML
  • Windows Media Metafiles for Faceplates
  • Faceplate Help Strings
  • How to Create a Simple Faceplate
  • How to Create a Faceplate with Basic Controls
  • Faceplate Samples


Creating an HTML Application Faceplate

This topic applies to Windows Media Player version 6.4 only.

The release of Microsoft® Internet Explorer 5 introduces the HTML Application (HTA), a new file type for the Microsoft® Windows® platform. The file name extension for HTA files is .hta. They use standard HTML formatting tags to display content and graphics, and allow user interaction through scripting. Although HTA files look much like standard HTML files, they incorporate the new HTA:APPLICATION tag to specify properties of the HTML application and the browser window. By setting browser window properties, the window can appear to users as a standard Windows application. Because a faceplate is an HTA file with an embedded Windows Media Player object controlled through scripts, it is much easier to create than a stand-alone Windows application.

To create an HTA file, create a standard HTML file and add an HTA:APPLICATION tag as shown in the following example:

<HTML>
<HEAD>
    <SCRIPT>
        window.resizeTo(330,518);
    </SCRIPT>

    <TITLE>Media Player Faceplate</TITLE>

    <HTA:APPLICATION
        CAPTION="true"
        MAXIMIZEBUTTON="no"
    >
</HEAD>

<BODY SCROLL="no">

<CENTER>
    <B>A Simple Faceplate</B>
</CENTER>

The one-line script within the SCRIPT tags resizes the window to the dimensions of Windows Media Player and the title area. This step is necessary because otherwise the window dimensions would use whatever default values were defined previously for Microsoft Internet Explorer, which probably are not the desired dimensions.

The HTA:APPLICATION tag must be located inside the HEAD tag of any HTA file. With this tag you can specify properties of the HTML application and the browser window it shows to users. Setting the CAPTION attribute to true produces a top menu bar, enabling users to reposition and close the browser window. Setting the MAXIMIZEBUTTON attribute to no disables the Maximize button on the menu bar. This prevents users from filling their entire screen with the browser window. There is a Minimize button on the menu bar by default; it can be disabled by setting the MINIMIZEBUTTON attribute to no.

The procedure for placing a Windows Media Player control in a faceplate is the same used for an HTML file. Next, place an OBJECT tag in the HTA file, as shown below. The OBJECT tag can be placed by itself or inside a TABLE, DIV, or SPAN tag. The following example creates a basic Windows Media Player object.

<OBJECT ID="MediaPlayer"
    CLASSID="CLSID:22d6f312-b0f6-11d0-94ab-0080c74c7e95"
    WIDTH="320"
    HEIGHT="508"
    STYLE="position:absolute; left:0px; top:70px;"
    >
    <PARAM NAME="FileName" VALUE="../art/media/lunchtime.asf">
    <PARAM NAME="AutoStart" VALUE="0">
    <PARAM NAME="ShowControls" VALUE="1">
    <PARAM NAME="ShowStatusBar" VALUE="1">
    <PARAM NAME="ShowDisplay" VALUE="1">
</OBJECT>

</BODY>
</HTML>

The object ID specified by the ID attribute is the name you will use to access this instance of the player through scripts. To use the version of Windows Media Player included with this SDK, you must specify the CLASSID parameter as shown above.

The WIDTH and HEIGHT attributes specify the width and height of the entire display window used for the Windows Media Player object, including the control buttons, position trackbar, and video display panel. If you want to use the standard Windows Media Player user interface for your object, you may need to size this window to be a little taller than the actual video display window to make room for the control buttons and display panel. If you are going to use a custom user interface, you can hide the buttons and trackbar from view. When you do this, the width and height reflect the size of the video display window. If you are using Windows Media Player for audio-only playback with your own user interface, you can hide the entire Windows Media Player object by setting the HEIGHT and WIDTH parameters to zero.

Within the OBJECT tag, you can also specify a number of initial settings with a series of PARAM tags. The NAME attribute in a PARAM tag corresponds to one of the Windows Media Player control properties. The most important of these is the FileName property, which specifies the media file for the Windows Media Player to use. There are many others properties, specifying which controls to show, whether the clip begins playing after the page loads, and other behaviors. Setting these properties during object creation is optional; if you prefer, you can set them later, in your script.

The Windows Media Player object also accepts STYLE settings, which are useful for positioning the viewing window. Styles are discussed in further detail in Faceplate Layout in DHTML.


Controlling the Windows Media Player from Scripts

This topic applies to Windows Media Player version 6.4 only.

Windows Media Player faceplates are possible because all the functionality of Windows Media Player is exposed to Web scripting languages. Anything you can do with the stand-alone Windows Media Player application, such as pushing the play button, you can also do with a corresponding script command. Scripts can also retrieve information from the Windows Media Player control. Combined, these features enable scripts to make changes in the dynamic HTML (DHTML) faceplate graphics that correspond to changes in the operational state of Windows Media Player.

This article contains the following sections.

  • Performing Basic Playback Operations
  • Getting Information from the Windows Media Player
  • Handling Events in Faceplates


Performing Basic Playback Operations

This topic applies to Windows Media Player version 6.4 only.

When you open Windows Media Player as a stand-alone application, you are presented with a video display window and standard control buttons that mimic the functions of most VCRs and compact disc players. These buttons control basic playback operations for all media; listed from left to right (see illustration), these are:

  • Play
  • Pause
  • Stop
  • Previous Track
  • Fast Reverse
  • Fast Forward
  • Next Track

Scripts can perform these operations by invoking methods on the Windows Media Player control. The correspondence between the operations and methods is shown in the table below.

Operation | Method
Play | MediaPlayer.Play();
Pause | MediaPlayer.Pause();
Stop | MediaPlayer.Stop();
Previous Track | MediaPlayer.Previous();
Fast Reverse | MediaPlayer.FastReverse();
Fast Forward | MediaPlayer.FastForward();
Next Track | MediaPlayer.Next();

Another element of the Windows Media Player interface is the position trackbar, a slider control that displays the elapsed time of the current track. For scripting, this position is stored in a read/write property called CurrentPosition. While a track is playing, the value of this property is the current elapsed time, in seconds. Comparing this value with the value of the Duration property yields the percentage of the total track time that has elapsed. To jump to an arbitrary time in a track, assign a new value to CurrentPosition.

Volume is also controlled by a slider, and is handled in script in a similar way. The read/write Volume property stores a value for the current volume setting. To change the volume, assign a new value to this property. Valid values range from -10,000 for the lowest setting to zero for the loudest setting. There is also a mute button on the control panel, which turns off all sound output from Windows Media Player. You can toggle muting in script by assigning a Boolean value of either true or false to the Mute property.


Getting Information from Windows Media Player

This topic applies to Windows Media Player version 6.4 only.

The Windows Media Player control stores information about its current activity and the files it can play. Most information is stored as the value of a property, which scripts can retrieve, although some information is accessed as a return value of a script function.

Any time you send script commands to it, the Windows Media Player control may already be playing a file, scanning through a file, skipping to another file, or waiting to play a file. The PlayState property indicates what action the Windows Media Player control is performing at the time the property is read. By reading this property, you can decide the best action to perform for a command based on its current play state. For example, if your script calls a function whenever a user hits the play button, the function should check to see if the Windows Media Player control is already playing a file. A Microsoft® JScript® function that performs this check might look like the following.

function onPlay()
{
    if (MediaPlayer.PlayState != 2) // If not already playing a file...
    {
        MediaPlayer.Play();
        playBtn.SelectActive();
        pauseBtn.SelectNormal();
        stopBtn.SelectNormal();
    }
}

If you were to call the Play method while Windows Media Player was already playing a file, the call would have no effect on the Windows Media Player operation. To avoid this case, the onPlay function checks first to see if the PlayState property is not equal to 2 (which is the value of that property when a file is currently playing) before performing any operations. If Windows Media Player is not currently playing a file, this function would start playback and change the appearance of the buttons on the faceplate to reflect the new state. In this example, the faceplate graphics are changed by the script commands SelectActive and SelectNormal, defined elsewhere on the page for each graphical button.

If Windows Media Player uses a Windows Media metafile to define the media files for playback, your script can retrieve information contained in the metafile. While a media file is currently playing, the GetMediaInfoString method can return the author, title, and copyright information, as specified by the Windows Media metafile entry for that media file. In addition, the GetMediaParameter method enables you to retrieve custom parameters, defined in the metafile with PARAM tags. (For more information, see Windows Media Metafiles for Faceplates and Windows Media Metafiles.)


Handling Events in Faceplates

This topic applies to Windows Media Player version 6.4 only.

At various times during its operation, Windows Media Player generates events, which can be handled by scripts. This can be useful for resetting your control button graphics when a media file finishes playing, or displaying new clip information on the faceplate when a new media file begins playing.

This is done in Microsoft® JScript® by specifying a script that will execute in response to a particular event, and placing it inside a SCRIPT tag. The FOR parameter of the SCRIPT tag gives the name of the Windows Media Player object (as defined in the OBJECT tag), and the EVENT parameter specifies the name of the event plus any parameter names.

For example, when a clip finishes playback, Windows Media Player generates an EndOfStream event. The following example script would be called any time the Windows Media Player reached the end of a media file and the EndOfStream event occurred:

<SCRIPT FOR="MediaPlayer"
        EVENT="EndOfStream(bResult)"
        LANGUAGE="JScript">
    if (bResult == 0)
    {
        MediaPlayer.Stop();
        playBtn.SelectNormal();
        stopBtn.SelectActive();
        pauseBtn.SelectNormal();
    }
</SCRIPT>

The EndOfStream event passes one parameter to the script. If the clip has played all the way through, the value of this parameter is zero. In that instance, the script calls the Stop method to make sure playback is stopped and resets the control button graphics to reflect the new state.

For a full list of supported Windows Media Player events, consult Windows Media Player Events in the Version 6.4 Control Reference.


Faceplate Layout in DHTML

This topic applies to Windows Media Player version 6.4 only.

The user interface for a Windows Media Player faceplate is a Web page written in dynamic HTML (DHTML). The page should be designed to generate events that trigger certain scripts contained in the page. These scripts in turn control playback and the presentation of any information specific to the media file. Because DHTML allows you to change the text and graphics of a Web page after it has loaded, you can change the appearance of the faceplate as Windows Media Player performs different tasks. Because the faceplate is a Web page, it can also contain hyperlinks to informational and storefront Web sites, and these can change with each media file being played.

To make a good faceplate, you need some knowledge of DHTML and Cascading Style Sheets (CSS). Microsoft's SiteBuilder Network has excellent reference material on both of these topics. You will also need some good graphical editing tools, because faceplates can use images for both interface elements and pictures related to the media. With these tools in hand, constructing a faceplate is not much different from constructing a Web page.

This article contains the following sections.

  • Positioning Faceplate Elements
  • Connecting the Faceplate to Windows Media Player


Positioning Faceplate Elements

This topic applies to Windows Media Player version 6.4 only.

Windows Media Player allows you to specify the size and positioning of its display window with the STYLE attribute of its OBJECT tag. This is especially useful for creating custom video displays, where the video display window must be in a certain location on the page. The following OBJECT tag creates a video display that is 320 pixels wide by 240 pixels high, positioned 70 pixels below the upper-left corner of the screen.

<OBJECT ID="MediaPlayer"
    CLASSID="CLSID:22d6f312-b0f6-11d0-94ab-0080c74c7e95"
    WIDTH="320"
    HEIGHT="240"
    STYLE="position:absolute;
        left:0px;
        top:70px;"
    >
    <PARAM NAME="FileName" VALUE="../art/media/lunchtime.asf">
    <PARAM NAME="AutoStart" VALUE="0">
    <PARAM NAME="ShowControls" VALUE="0">
    <PARAM NAME="ShowStatusBar" VALUE="0">
    <PARAM NAME="ShowDisplay" VALUE="0">
</OBJECT>

For this instance of the Windows Media Player control, the ShowControls, ShowStatusBar, and ShowDisplay properties have been set to zero. This disables the standard user interface for Windows Media Player, leaving only the video display window showing.

Any faceplate you construct will contain a number of text and image elements, which could be user interface buttons, descriptive text, hyperlinked text, or Windows Media Player display windows. You can position these elements in any way you like, to produce whatever layout you find most appealing. For the most precise control over positioning, it is common to use nested SPAN and DIV tags. Each of these tags can act as a container for graphics or text, and with the STYLE attribute you can position the element exactly on the faceplate.

The following is a section of a faceplate file that uses this positioning method for an "Author" text field.

<DIV STYLE="position:absolute;
    left:100px;
    top:50px;
    width:200px;
    height:133px;" >
    <SPAN ID="authorField"
        STYLE="position:absolute;
            left:44px;
            top:90px;
            width:50px;
            height:16px;
            font-size:9px;
            color:6699cc;
            text-align:left;" >
   Author:
   </SPAN>
</DIV>

The DIV in the above example is 200 by 133 pixels, located 100 pixels from the left and 50 pixels from the top of the upper left corner of the faceplate. It acts as a container for the enclosed SPAN tag, which specifies a region to display author information for the faceplate. Although the STYLE parameter for the SPAN tag specifies absolute positioning, the coordinates are relative to the enclosing DIV tag. This behavior allows you to group elements within a container and move them all without changing their relative positions. For text display, you can also specify different fonts, font sizes, colors, or alignments.

The SPAN tag in the above example specifies an ID attribute, so that the text it contains can be modified later by scripts when Windows Media Player opens a new file. For this tag, a script command that modifies the text would look like the following.

authorField.innerText = "Author: " + MediaPlayer.GetMediaInfoString(9);


Connecting the Faceplate to Windows Media Player

This topic applies to Windows Media Player version 6.4 only.

In addition to specifying STYLE attributes, with DHTML you can specify event handlers for the DIV and SPAN tags. These events can be mouse clicks or keystrokes initiated by the user which cause certain Windows Media Player actions to happen. They can also initiate changes to the faceplate graphics.

A common user interface element for a faceplate would be a play button. In DHTML, this is how a tag that specifies event handler scripts might look.

<SPAN ID="PlayButtonSpan"
    STYLE="position:absolute;
        left:493px;
        top:216px;
        width:35px;
        height:31px;"
    onClick="onPlay()"
    onMouseOver="onPlayMouseOver()"
    onMouseOut="onPlayMouseOut()" >
    <IMG NAME="PlayButton"
        WIDTH=35
        HEIGHT=31
        SRC="../art/demo2/play_N.GIF" >
</SPAN>

As before, the STYLE attribute specifies the size and position of the button. In this example, however, there are three event handlers specified for any mouse events that may occur on the region of the SPAN tag. The onMouseOver event happens when a user moves the mouse into the SPAN tag, and the onMouseOut event happens when the mouse moves out of that region. Each of these events calls a script function that switches the graphic used for the play button, indicating to users that this region of the screen controls a function for Windows Media Player.

The onClick event happens when a user clicks the mouse button once over the region. For this button, the event causes the onPlay function to be called. This function, which is defined in the script, is shown below.

function onPlay()
{
    if(MediaPlayer.PlayState != 2)
    {
        MediaPlayer.Play();
        playBtn.SelectActive();
        pauseBtn.SelectNormal();
        stopBtn.SelectNormal();
        startTrackbar();
    }
}

First the script checks to see whether Windows Media Player is already playing a file. If not, it calls the Windows Media Player Play method to start playback of the current file. The next three script calls are functions that change the graphics of the play button, pause button, and stop button to reflect the current play state of Windows Media Player. The last script call starts another script that monitors the progress of the playback and displays the elapsed and total playback time in text on the faceplate.

Event handlers for events such as onClick can also be created for the Windows Media Player object. For more information, see Handling Events.


Windows Media Metafiles for Faceplates

This topic applies to Windows Media Player version 6.4 only.

The last requirement for a Windows Media Player faceplate is a collection of media files to play. The playback of these files is organized in a Windows Media metafile. These files not only specify the playback order of media files, but also contain information and related links for each file.

While a file is playing, your script can retrieve information specified in the Windows Media metafile through the GetMediaInfoString method. This method can access the AUTHOR, COPYRIGHT, TITLE, and other information for the current clip or show.

A Windows Media metafile can also store this information in PARAM tags for each media file entry. In this case, use the GetMediaParameter method to access the information. This method is more flexible than GetMediaInfoString, because it allows you to retrieve information for the entire playlist, not just the current clip.

The names and information contained in PARAM tags are determined entirely by the creator of the Windows Media metafile, and can be used with custom scripts for any purpose.

The sample metafile below shows the use of PARAM tags within metafile entries.

<ASX VERSION="3.0">
    <TITLE>Example Media Player Show</TITLE>
    <PARAM NAME="Director" VALUE="Jane D." />

    <ENTRY>
        <TITLE>Example Clip</TITLE>
        <REF HREF="http://samples.microsoft.com/media.asf" />
        <PARAM NAME="Title" VALUE="Example Clip" />
        <PARAM NAME="Location" VALUE="North America" />
        <PARAM NAME="Release Date" VALUE="March 1998" />
    </ENTRY>

    <ENTRY>
        <TITLE>Another Clip</TITLE>
        <REF HREF="http://samples.microsoft.com/more_media.asf" />
        <PARAM NAME="Title" VALUE="Another Clip" />
        <PARAM NAME="Location" VALUE="Japan" />
        <PARAM NAME="Release Date" VALUE="December 1996" />
    </ENTRY>
</ASX>

Note Title information for each entry is repeated inside a PARAM tag, making all the information for each entry available to the GetMediaParameter method.


Faceplate Help Strings

This topic applies to Windows Media Player version 6.4 only.

To help users learn about the actions of the different buttons and areas on your faceplate, you can add ToolTip help strings to any HTML image or element. When writing ToolTips for standard Windows Media Player functions such as "Play" or "Stop", you should use the same strings that are also used by the Windows Media Player application. This provides users with a consistent interface over a wide variety of faceplate styles.

To add a ToolTip to your faceplate, include a TITLE attribute for the HTML element in question, assigning it a value that is the string to be displayed. For example, the following code creates a standardized ToolTip for the play button.

<IMG ID="btnPlay" onMouseOver="imgRollon()" onMouseOut="imgRolloff();"
onclick="Play()" SRC="images/btnPlay.gif" TITLE="Play">

Now, when a mouse pointer hovers over the play button, the ToolTip "Play" will appear in a small box next to the pointer.

The following table shows the standard Windows Media Player ToolTip strings that you should use in your faceplates, as well as the action that the element described by the ToolTip should perform.

ToolTip string | Action
Play | Begins playing the open media file. By default, a file begins to play automatically when it is opened.
Pause | Pauses the open media file. Click Play to resume.
Stop | Stops the playback of the current file. Stop does not close the file or your connection to a server.
Skip Back | Returns to the beginning of the current clip, or, if at the beginning, returns to the beginning of the previous clip. Only available if the clip is part of a show.
Rewind | Rewinds the current clip. Only available with certain types of stored (not live) media. When you release the Rewind button, Windows Media Player begins playing again.
Fast Forward | Advances forward through the clip. Only available with certain types of stored (not live) media. When you release the Fast forward button, Windows Media Player begins playing again.
Skip Forward | Begins playing the beginning of the next clip. Only available if a show is open.
Preview each clip in a playlist | Plays a short section of each clip in a show. Usually, each clip plays for 10 seconds, but an individual show may have a different preview duration.
Mute | Silences the audio content of the file. Click Mute again to hear the soundtrack.
Volume Control | Controls the volume level of the content you are viewing.


How to Create a Simple Faceplate

This topic applies to Windows Media Player version 6.4 only.

This article walks through the code used to create a basic faceplate. The faceplate consists of a standard Windows Media Player object in a window, with a centered title placed above the Windows Media Player. The window itself has a title and standard Close and Minimize buttons. To view the sample, see Simple Faceplate in the Samples folder that was installed with the SDK.

This article contains the following sections.

  • Creating an HTML Application
  • Embedding the Windows Media Player
  • What Next?


Creating an HTML Application

This topic applies to Windows Media Player version 6.4 only.

The file begins like an ordinary HTML file, but includes an in-line script and an HTA:APPLICATION tag, as shown below.

<HTML>
<HEAD>
    <SCRIPT>
        window.resizeTo(330,448);
    </SCRIPT>

    <TITLE>Media Player Faceplate</TITLE>

    <HTA:APPLICATION
        CAPTION="true"
        MAXIMIZEBUTTON="no"
    >
</HEAD>

The one-line script within the SCRIPT tags resizes the window to the dimensions of Windows Media Player and its title area. This step is necessary because otherwise the window dimensions would use whatever default values were defined previously for Microsoft® Internet Explorer, which probably are not the desired dimensions.

The HTA:APPLICATION tag was introduced with Microsoft® Internet Explorer 5 to be used with the HTA file type. With this tag you can specify properties of the HTML application and the browser window it shows to users. It must be located inside the HEAD tag of any HTA file. Setting the CAPTION attribute to true produces the top menu bar, enabling users to reposition and close the browser window. Setting the MAXIMIZEBUTTON attribute to no disables the Maximize button on the menu bar. This prevents users from filling their entire screen with the much smaller faceplate. There is a Minimize button on the menu bar by default; it can be disabled by setting the MINIMIZEBUTTON attribute to no.


Embedding the Windows Media Player

This topic applies to Windows Media Player version 6.4 only.

The remainder of the file displays the faceplate title and positions the Windows Media Player control in the page. The complete sample code follows.

<HTML>
<HEAD>
    <SCRIPT>
        window.resizeTo(330,448);
    </SCRIPT>

    <TITLE>Media Player Faceplate</TITLE>

    <HTA:APPLICATION
        CAPTION="true"
        MAXIMIZEBUTTON="no"
    >
</HEAD>

<BODY SCROLL="no">

<CENTER>
    <B>A Simple Faceplate</B>
</CENTER>

<OBJECT ID="MediaPlayer"
    CLASSID="CLSID:22d6f312-b0f6-11d0-94ab-0080c74c7e95"
    WIDTH="320"
    HEIGHT="508"
    STYLE="position:absolute;
        left:0px;
        top:70px;"
    >
    <PARAM NAME="FileName" VALUE="../art/media/lunchtime.asf">
    <PARAM NAME="AutoStart" VALUE="0">
    <PARAM NAME="ShowControls" VALUE="1">
    <PARAM NAME="ShowStatusBar" VALUE="1">
    <PARAM NAME="ShowDisplay" VALUE="1">
</OBJECT>

</BODY>
</HTML>

Setting the SCROLL attribute of the BODY tag to no eliminates the scroll bars from the page, which maximizes the usable area of the faceplate. The faceplate title is simply HTML text centered at the top of the page. The OBJECT tag creates an instance of the Windows Media Player control with all standard interface controls enabled. The STYLE attribute provides precise positioning.

The Windows Media Player control object is initialized with a series of PARAM tags that set the values of several properties. The most important of these is the FileName property, which specifies which file the Windows Media Player will use for playback. The file can be a single media file (such as a file with an .avi or .asf file name extension), or a Windows Media metafile that lists several media files to be played in a certain order. The AutoStart property is set to zero, indicating that Windows Media Player should not start playing the file right away. Finally, the ShowControls, ShowStatusBar, and ShowDisplay properties indicate that Windows Media Player should display its standard user interface, in order for the user to control and monitor playback from the Web page.


What Next?

This topic applies to Windows Media Player version 6.4 only.

This sample was intended as the most basic example of a Windows Media Player faceplate. With a little more work, you can give your faceplate a customized appearance and user controls. The Faceplate with Basic Controls uses graphical buttons and dynamic HTML (DHTML) events to control the Windows Media Player.

For more information on Internet Explorer HTML Applications, see the overview and reference pages on the Microsoft SiteBuilder Network.


How to Create a Faceplate with Basic Controls

This topic applies to Windows Media Player version 6.4 only.

This article walks through the code used to create a faceplate with a custom user interface to the Windows Media Player control. The faceplate displays a play button, a stop button, and a pause button, each with its own script that operates the Windows Media Player control. To view the sample, see Faceplate with Basic Controls in the Samples section.

This article contains the following sections.

  • Laying Out the User Interface
  • Adding Button Click Events


Laying Out the User Interface

This topic applies to Windows Media Player version 6.4 only.

Start by positioning and sizing the faceplate window, as shown in the following example.

<HTML>
<HEAD>

    <SCRIPT>
        var sampleWidth = 297;
        var sampleHeight = 292;
        window.resizeTo(sampleWidth,sampleHeight);

        var screenPosX = screen.availWidth/2 - sampleWidth/2;
        var screenPosY = screen.availHeight/2 - sampleHeight/2;
        window.moveTo(screenPosX, screenPosY);
    </SCRIPT>

    <TITLE>Windows Media Player Faceplate</TITLE>

    <HTA:APPLICATION
        CAPTION="true"
        MAXIMIZEBUTTON="no">
</HEAD>

The script included here centers the window in the screen and sets it to the proper size for the Windows Media Player control. The attributes specified for the HTA:APPLICATION tag specify that the window will have a menu bar for repositioning, and disable the Maximize button so that the window size will remain the same.

The following tags lay out the title graphic and the Windows Media Player video display panel.

<BODY SCROLL="no" BGCOLOR="#000000">

<SPAN STYLE="position:absolute;
    left:8px;
    top:2px;
    width:221px;
    height:20px;"
    >
    <IMG SRC="../art/sample2/title.gif">
</SPAN>

<OBJECT ID="MediaPlayer"
    CLASSID="CLSID:22d6f312-b0f6-11d0-94ab-0080c74c7e95"
    WIDTH="282"
    HEIGHT="200"
    STYLE="position:absolute;
        left:0px;
        top:24px;"
    >
    <PARAM NAME="FileName" VALUE="../art/media/dove.asf">
    <PARAM NAME="AutoStart" VALUE="0">
    <PARAM NAME="ShowControls" VALUE="0">
    <PARAM NAME="ShowStatusBar" VALUE="0">
    <PARAM NAME="ShowDisplay" VALUE="0">
    <PARAM NAME="ClickToPlay" VALUE="0">
</OBJECT>

The title graphic is contained in a SPAN tag positioned near the upper left corner of the window. The Windows Media Player video display is positioned below the title and flush to the left of the screen. The PARAM tags set various properties of the Windows Media Player. The AutoStart and ClickToPlay properties are set to false, so that playback will be controlled entirely by the faceplate buttons (added later in the file). Also, note that unlike the Simple Faceplate, this faceplate sets the ShowControls, ShowStatusBar, and ShowDisplay properties to false. Doing so turns off the standard interface controls built in to the Windows Media Player, leaving only the video display panel showing. The custom user interface will take the place of the standard controls.


Adding Button Click Events

This topic applies to Windows Media Player version 6.4 only.

The following SPAN tags position the images for the play, pause, and stop buttons.

<SPAN STYLE="position:absolute;
    left:0px;
    top:224px;
    width:94px;
    height:38px;"
    ONCLICK="MediaPlayer.Play()"
    >
    <IMG SRC="../art/sample2/play.gif"></SPAN>

<SPAN STYLE="position:absolute;
    left:94px;
    top:224px;
    width:94px;
    height:38px;"
    ONCLICK="MediaPlayer.Stop();MediaPlayer.CurrentPosition=0;"
    >
    <IMG SRC="../art/sample2/stop.gif"></SPAN>

<SPAN STYLE="position:absolute;
    left:188px;
    top:224px;
    width:94px;
    height:38px;"
    ONCLICK="onPause();"
    >
    <IMG SRC="../art/sample2/pause.gif">
</SPAN>

Much of the HTML in the above example is for positioning the buttons on the faceplate. However, note that each SPAN tag has an ONCLICK attribute that specifies a script command for the onClick event. This is the crucial link between dynamic HTML (DHTML) and the Windows Media Player object. When a user clicks on one of the spans containing a button graphic, it calls the specified script.

The scripts for the play and stop buttons are simple. The first calls the Play method, and the other sets the CurrentPosition property to zero.

The script for the pause button is somewhat more complicated, because the button has a more complex behavior. If clicking the button called the Pause method and did nothing else, the user would have to click the play button to restart playback. Typically a pause button will also restart playback from a paused state, so it's a good idea for a custom faceplate to act the same way. The following script function makes the pause button toggle between calling the Play method and calling the Pause method.

function onPause()
{
    if(MediaPlayer.PlayState==1)
        MediaPlayer.Play();
    else if(MediaPlayer.PlayState==2)
        MediaPlayer.Pause();
}

The value of the PlayState property reflects what Windows Media Player is doing at any time. If the value equals 1, Windows Media Player is in a paused state, and the above script responds by resuming playback. Otherwise, Windows Media Player was not paused, and the script calls the Pause method.


Faceplate Samples

This topic applies to Windows Media Player version 6.4 only.

The following samples implement basic and more advanced Windows Media Player user interfaces with HTML application faceplates. They are available in the Samples directory that was installed with the SDK.

Sample | Description
Simple Faceplate | This short sample embeds the Windows Media Player control object in an HTML file.
Basic Controls | This sample shows how to create graphical buttons for a custom Windows Media Player interface. It also shows how to link dynamic HTML (DHTML) events to scripts that control Windows Media Player.


Version 6.4 Object Model Reference

This section contains all the Windows Media Player Object Model version 6.4 scripting reference information, including reference entries for the events, methods, properties, and objects supported by the Windows Media Player Object Model version 6.4.

Section
Properties
Methods
Events
Objects


Windows Media Player Object Model Version 6.4 Properties

Windows Media Player Object Model version 6.4 supports the following properties.

Property | Description
AllowChangeDisplaySize | Specifies or retrieves a value indicating whether the display size can be changed.
AllowScan | Specifies or retrieves a value indicating whether scanning is enabled for files that support scanning (fast-forwarding and rewinding).
AnglesAvailable | Retrieves the number of available angles.
AnimationAtStart | Specifies or retrieves a value indicating whether animation runs before the first image is displayed.
AudioStream | Specifies or retrieves the stream number of the current audio stream.
AudioStreamsAvaliable | Retrieves the number of available audio streams.
AutoRewind | Specifies or retrieves a value indicating whether the Windows Media Player control automatically returns to the clip's starting point after the clip finishes playing or has otherwise stopped.
AutoSize | Specifies or retrieves a value indicating whether the Windows Media Player control automatically resizes to accommodate the current media item at the size specified by the DisplaySize property.
AutoStart | Specifies or retrieves a value indicating whether to start playing the clip automatically.
Balance | Specifies or retrieves a value indicating the stereo balance.
Bandwidth | Retrieves the bandwidth of the current clip in bits per second.
BaseURL | Retrieves a value indicating the base URL.
BufferingCount | Retrieves the number of times buffering occurred during playback of a clip.
BufferingProgress | Retrieves the percentage of buffering completed.
BufferingTime | Retrieves a the buffering time in seconds.
ButtonsAvailable | Retrieves the number of available buttons.
CanPreview | Retrieves a value indicating whether the current content contains a playlist that can be previewed.
CanScan | Retrieves a value indicating whether the current file supports scanning.
CanSeek | Retrieves a value indicating whether the current file has the ability to seek to a specific time.
CanSeekToMarkers | Retrieves a value indicating whether markers in the file can be located with a seek operation.
CaptioningID | Retrieves the name of the frame or control that displays captioning.
CCActive | Specifies or retrieves a value indicating whether closed captioning is on or off.
ChannelDescription | Retrieves the station description.
ChannelName | Retrieves the station name.
ChannelURL | Retrieves the URL of the station metafile.
ClickToPlay | Specifies or retrieves a value indicating whether the user can toggle playback on and off by clicking the video image.
ClientID | Retrieves the unique ID of a client.
CodecCount | Retrieves the number of installable codecs used by the current clip.
ColorKey | Specifies or retrieves the color key being used by the DVD playback.
ConnectionSpeed | Retrieves the bandwidth selected during setup.
ContactAddress | Retrieves the station's contact address.
ContactEmail | Retrieves the station's e-mail address.
ContactPhone | Retrieves the station's contact telephone number.
CreationDate | Retrieves the date and time when the clip was created.
CurrentAngle | Specifies or retrieves a number identifying the current camera angle
CurrentAudioStream | Specifies or retrieves a value indicating the current audio stream.
CurrentButton | Retrieves the number of the current button.
CurrentCCService | Specifies or retrieves a value indicating the current closed captioning service.
CurrentChapter | Retrieves the chapter number currently being played.
CurrentDiscSide | Retrieves the current disc side.
CurrentDomain | Retrieves the current DVD domain of the DVD player.
CurrentMarker | Specifies or retrieves the current marker number.
CurrentPosition | Specifies or retrieves the clip's current position, in seconds.
CurrentSubpictureStream | Specifies or retrieves a value indicating the source of the subpicture.
CurrentTime | Retrieves a the current playback time.
CurrentTitle | Retrieves the number of the title currently being played.
CurrentVolume | Retrieves the volume number for the current root directory.
CursorType | Specifies or retrieves the cursor type.
DefaultFrame | Specifies or retrieves a value representing the default target HTTP frame.
DisplayBackColor | Specifies or retrieves the background color of the display panel.
DisplayForeColor | Specifies or retrieves the foreground color of the display panel.
DisplayMode | Specifies or retrieves a value indicating whether the status bar displays the current position in seconds or frames.
DisplaySize | Specifies or retrieves the size of the image display window.
Duration | Retrieves the length of the clip, in seconds.
DVD | Retrieves the Windows Media Player control DVD interface.
EnableContextMenu | Specifies or retrieves a value indicating whether the context menu appears when the user clicks the right mouse button.
Enabled | Specifies or retrieves a value indicating whether the Windows Media Player control is enabled.
EnableFullScreenControls | Specifies or retrieves a value indicating whether Windows Media Player displays controls in full-screen mode.
EnablePositionControls | Specifies or retrieves a value indicating whether the position controls are enabled on the control bar.
EnableTracker | Specifies or retrieves a value indicating whether the trackbar control is enabled.
EntryCount | Retrieves the number of entries contained in the current Windows Media metafile.
ErrorCode | Retrieves the current error code.
ErrorCorrection | Retrieves the error correction type of the current clip.
ErrorDescription | Retrieves a description of the current error state.
FileName | Specifies or retrieves the name of the clip to play.
FramesPerSecond | Retrieves a value indicating the number of frames per second used by the DVD title.
HasError | Retrieves a value indicating whether the Windows Media Player control currently has an error.
HasMultipleItems | Retrieves a value indicating whether the current clip contains multiple items (playlists).
ImageSourceHeight | Retrieves the original image height of the current clip, in pixels.
ImageSourceWidth | Retrieves the original image width of the current clip, in pixels.
InvokeURLs | Specifies or retrieves a value indicating whether the Windows Media Player control automatically invokes URLs in a browser (URL flipping).
IsBroadcast | Retrieves a value indicating whether the source is broadcast.
IsDurationValid | Retrieves a value indicating whether the value of the Duration property is valid.
Language | Specifies or retrieves a value indicating the current locale used for national language support.
LostPackets | Retrieves the number of packets lost during transmission of the stream.
MarkerCount | Retrieves the number of markers in the current clip.
Mute | Specifies or retrieves the current mute state of the Windows Media Player control.
OpenState | Retrieves the state of the content source.
PlayCount | Specifies or retrieves the number of times a clip plays.
PlayState | Retrieves a value indicating the state of the Windows Media Player operation.
PreviewMode | Specifies or retrieves a value indicating whether Windows Media Player is in preview mode.
Rate | Specifies or retrieves the playback rate of the clip.
ReadyState | Retrieves the state of readiness of the Windows Media Player control.
ReceivedPackets | Retrieves the number of packets received.
ReceptionQuality | Retrieves the percentage of packets received in the last 30 seconds.
RecoveredPackets | Retrieves the number of packets recovered.
Root | Specifies or retrieves a value indicating the directory that contains the DVD volume.
SAMIFileName | Specifies or retrieves the name of the file that contains the closed captioning information.
SAMILang | Specifies or retrieves a value indicating the language displayed for closed captioning.
SAMIStyle | Specifies or retrieves a value representing the closed captioning style.
SelectionEnd | Specifies or retrieves the time within the current clip at which playback will stop.
SelectionStart | Specifies or retrieves the time within the current clip at which playback will begin.
SendErrorEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends error events.
SendKeyboardEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends keyboard events.
SendMouseClickEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends mouse click events.
SendMouseMoveEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends mouse move events.
SendOpenStateChangeEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends open state change events.
SendPlayStateChangeEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends play state change events.
SendWarningEvents | Specifies or retrieves a value indicating whether the Windows Media Player control sends warning events.
ShowAudioControls | Specifies or retrieves a value indicating whether the audio controls appear on the control bar.
ShowCaptioning | Specifies or retrieves a value indicating whether the closed caption area is visible and closed captioning is enabled.
ShowControls | Specifies or retrieves a value indicating whether the control bar is visible.
ShowDisplay | Specifies or retrieves a value indicating whether the display panel is visible.
ShowGotoBar | Specifies or retrieves a value indicating whether the Go To bar is visible.
ShowPositionControls | Specifies or retrieves a value indicating whether the position controls appear on the control bar.
ShowStatusBar | Specifies or retrieves a value indicating whether the status bar is visible.
ShowTracker | Specifies or retrieves a value indicating whether the trackbar is visible.
SourceLink | Retrieves the path to the current clip.
SourceProtocol | Retrieves a value indicating the protocol used to receive data.
StreamCount | Retrieves the number of media streams in the current clip.
SubpictureOn | Specifies or retrieves a value indicating whether the subpicture is displayed.
SubpictureStreamsAvailable | Retrieves the number of available subpicture streams.
TitlesAvailable | Retrieves the number of titles available in the current volume.
TotalTitleTime | Retrieves the total playback time for the current title.
TransparentAtStart | Specifies or retrieves a value indicating whether the Windows Media Player control is transparent before play begins and after play ends.
UniqueID | Retrieves the unique identifier associated with the DVD volume.
VideoBorder3D | Specifies or retrieves a value indicating whether the three-dimensional video border effect is enabled.
VideoBorderColor | Specifies or retrieves the color of the video border.
VideoBorderWidth | Specifies or retrieves the width of the video border, in pixels.
Volume | Specifies or retrieves the volume, in hundredths of decibels.
VolumesAvailable | Retrieves the number of volumes in the volume set.


Player6.AllowChangeDisplaySize

This property specifies or retrieves a value indicating whether the display size can be changed.

Syntax

MediaPlayer.AllowChangeDisplaySize

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The display size can be changed.
false | The display size cannot be changed

Remarks

This property determines whether the DisplaySize property can be set at run time. In addition, setting the AllowChangeDisplaySize property to true enables the Video Size item on the shortcut menu.

See Also

  • Customizing the User Interface
  • Player6.AllowChangeDisplaySize
  • Player6.DisplaySize


Player6.AllowScan

This property specifies or retrieves a value indicating whether scanning is enabled for files that support scanning (fast-forwarding and rewinding).

Syntax

MediaPlayer.AllowScan

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Scanning is enabled.
false | Scanning is disabled

Remarks

This property determines whether the FastForward and FastReverse methods are enabled. In addition, if this property is true, the end user can scan forward or back through a clip by clicking Scan Forward or Scan Rewind on the shortcut menu. While scanning, the position on the trackbar control moves rapidly forward or backward. To stop scanning, click the play button, stop button, or pause button. Setting this property to false also disables the fast forward and fast reverse buttons on the Media Player control window.

Note Only certain types of files can be scanned, regardless of the value of AllowScan. The CanScan property returns a Boolean value indicating whether the file can be scanned.

See Also

  • Playback Methods and Properties
  • Player6.CanScan


Player6.AnglesAvailable

This property retrieves the number of available angles.

Syntax

MediaPlayer.DVD.AnglesAvailable

Possible Values

This property is a read-only ULONG ranging from 1 to 9.

Remarks

Angles are interleaved video streams that contain the same scene shot from different camera angles. If this property returns 1, the current video does not contain multiple angles.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.AnimationAtStart

This property specifies or retrieves a value indicating whether animation runs before the first image displays.

Syntax

MediaPlayer.AnimationAtStart

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Animation runs before the first image displays.
false | Animation does not run before the first image displays.

Remarks

Setting this property to true makes the video display window play a short animation while a clip is buffering and loading. If the TransparentAtStart property is true, the AnimationAtStart property is ignored.

The animation clip cannot be customized.

See Also

  • Customizing the User Interface
  • Player6.AutoRewind
  • Player6.Stop
  • Player6.TransparentAtStart


Player6.AudioStream

This property specifies or retrieves the stream number of the current audio stream.

Syntax

MediaPlayer.AudioStream

Possible Values

This property is a read/write Long.

Remarks

This property is useful if your content contains multiple audio streams. For example, if a clip contains several audio streams encoded in different languages, this property can specify which language the Windows Media Player control uses when it renders the content.

See Also

  • Player6.StreamCount


Player6.AudioStreamsAvailable

This property retrieves the number of available audio streams.

Syntax

MediaPlayer.DVD.AudioStreamsAvailable

Possible Values

This property is a read-only ULONG.

Remarks

DVD has a maximum of 8 audio streams.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.AutoRewind

This property specifies or retrieves a value indicating whether the Windows Media Player control automatically returns to the clip's starting point after the clip finishes playing or has otherwise stopped.

Syntax

MediaPlayer.AutoRewind

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The clip rewinds automatically.
false | The clip does not rewind automatically.

Remarks

To retain the current position within the clip, set this property to false, or use the Pause method.

The state of the image display window after automatic rewinding is determined by other Windows Media Player control properties. The default behavior is to display the background color of the control. If the TransparentAtStart property is true, the control becomes transparent after the file finishes playing. If the AnimationAtStart property is true and TransparentAtStart is false, the clip image is shown.

If the PlayCount property is greater than 1, the current position returns to zero only after the file is played PlayCount times. Between plays, the last image of the file is shown while play is restarting.

See Also

  • Playback Methods and Properties
  • Player6.AutoStart
  • Player6.CurrentPosition


Player6.AutoSize

This property specifies or retrieves a value indicating whether the Windows Media Player control automatically resizes to accommodate the current media item at the size specified by the DisplaySize property.

Syntax

MediaPlayer.AutoSize

Possible Values

This property is a read/write Boolean containing one of the following values. See Remarks for default.

Value | Description
true | Automatic sizing is enabled.
false | Automatic sizing is disabled.

Remarks

For Web page applications, the default value is true unless width and height parameters are specified at design time, in which case the default value is false. For Windows-based applications the default is false, because the width and height of the control must be set at design time.

If this property is true, the Windows Media Player control overrides width and height parameters. When a clip is loaded, the control changes its dimensions to accommodate the media stream, as specified by the DisplaySize property.

If this property is false, the image is centered in the video display panel. If the dimensions of the video image are smaller than the display panel, the Windows Media Player control adds a video border around the image. If the video image is larger than the specified display panel area, the image shrinks to fit into the display panel. Windows Media Player renders data more efficiently when it resizes to the dimensions of the source content.

Note When the FileName property is set to DVD:, enabling DVD playback, the default value for the AutoSize property is always true, even if the width and height parameters are specified at design time. To ensure that AutoSize is false when the width and height parameters are specified, set the property to false by using the PARAM tag, as follows.

<PARAM NAME="AutoSize" VALUE="0">

For more information, see Setting Control Properties with the PARAM Tag in the section Placing the Windows Media Player Control in a Web Page.

See Also

  • Customizing the User Interface
  • Player6.DisplaySize


Player6.AutoStart

This property specifies or retrieves a value indicating whether to start playing the clip automatically.

Syntax

MediaPlayer.AutoStart

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The clip automatically starts playing when the FileName property is set or the Open method is called.
false | The clip does not start until the Play method is called or the user clicks the play button.

See Also

  • Playback Methods and Properties
  • Player6.FileName
  • Player6.Play
  • Player6.PlayCount


Player6.Balance

This property specifies or retrieves a value indicating the stereo balance.

Syntax

MediaPlayer.Balance

Possible Values

This property is a read/write Long ranging from –10,000 to 10,000. It has a default value of zero.

Remarks

The default value of zero indicates that the sound is balanced equally between the left and right speakers. A value of –10,000 indicates that all sound is going to the left speaker. A value of 10,000 indicates that all sound is going to the right speaker.

See Also

  • Playback Methods and Properties
  • Player6.Volume


Player6.Bandwidth

This property retrieves the bandwidth of the current clip in bits per second.

Syntax

MediaPlayer.Bandwidth

Possible Values

This property is a read-only Long.

Remarks

This property returns zero if the FileName property is not set. This property is only valid for streaming media.

See Also

  • Monitoring Stream Status and Network Reception


Player6.BaseURL

This property retrieves a value indicating the base URL.

Syntax

MediaPlayer.BaseURL

Possible Values

This property is a read-only String.

Remarks

Commands can be embedded among the sounds and images of a Windows Media file. A command is 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 indicating the type of command being sent, and the other indicating the command. The Windows Media Player control uses the type parameter to determine how it processes the command parameter. Any type of command can be embedded in a Windows Media stream to be handled by the ScriptCommand event.

One type of command is a URL. URLs received by the Windows Media Player control are invoked automatically in the user's default browser if the value of the InvokeURLs property is true.

The URL sent to the Windows Media Player control is processed relative to the base URL specified by the 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 base URL is concatenated with the relative URL as follows:

A trailing forward slash ("/") is added to the value of the BaseURL property.

Leading period ("."), backward slash ("\"), and forward slash characters are deleted from the relative URL.

The relative URL is added to the end of the base URL.

All slashes in the resulting fully qualified URL are pointed in the same direction (converted to forward or backward slashes) based on the direction of the first slash character in the new URL.

The Windows Media Player control version 6.4 supports the use of two periods ("..") in the relative URL to indicate the parent of the current location.

See Also

  • Player6.DefaultFrame
  • Player6.ScriptCommand
  • Processing Embedded Script Commands


Player6.BufferingCount

This property retrieves the number of times buffering occurred during playback of a clip.

Syntax

MediaPlayer.BufferingCount

Possible Values

This property is a read-only Long.

Remarks

Each time playback is stopped and restarted, this property resets to zero. It does not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time when the FileName property is set.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.Buffering
  • Player6.BufferingProgress
  • Player6.BufferingTime


Player6.BufferingProgress

This property retrieves the percentage of buffering completed.

Syntax

MediaPlayer.BufferingProgress

Possible Values

This property is a read-only Long.

Remarks

Each time playback is stopped and restarted, this property resets to zero. It does not reset if playback is paused.

Buffering only applies to streaming content. This property returns valid information only during run time, when the FileName property is set.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.Buffering
  • Player6.BufferingCount
  • Player6.BufferingTime


Player6.BufferingTime

This property retrieves the buffering time in seconds.

Syntax

MediaPlayer.BufferingTime

Possible Values

This property is a read-only Double ranging from 1 to 30. The default for Windows Media content is 5 seconds. The default for video-on-demand (VOD) content is 3 seconds.

Remarks

The buffering time is the number of seconds the Windows Media Player control allocates for buffering incoming data before playback begins.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.Buffering
  • Player6.BufferingCount
  • Player6.BufferingProgress


Player6.ButtonsAvailable

This property retrieves the number of available buttons.

Syntax

MediaPlayer.DVD.ButtonsAvailable

Possible Values

This property is a read-only ULONG.

Remarks

If buttons are not present, this property returns zero.


Player6.CanPreview

This property retrieves a value indicating whether the current content contains a playlist that can be previewed.

Syntax

MediaPlayer.CanPreview

Possible Values

This property is a read-only Boolean.

Remarks

If the value of this property is true, Windows Media Player can be operated in preview mode by setting the PreviewMode property to true. When Windows Media Player is in preview mode, it renders a few seconds of each clip in the playlist. By default, the length of time each clip plays is 10 seconds; however, you can set the preview duration in a Windows Media metafile with the PREVIEWDURATION element.

See Also

  • Player6.PreviewMode
  • Using Playlists


Player6.CanScan

This property retrieves a value indicating whether the current file supports scanning.

Syntax

MediaPlayer.CanScan

Possible Values

This property is a read-only Boolean.

Remarks

If the value of this property is true, the current file can be scanned (fast-forwarded or fast-reversed), provided that the AllowScan property is set to true.

If a media file has not been selected for the player, by setting the FileName property or calling the Open method, the value of this property will be false.

Video on demand (VOD) and Windows Media files both support scanning; however, Windows Media content can be scanned only if the following conditions are all true:

  • The file is indexed.
  • The file is playing from a Microsoft® NetShow™ unicast server (not playing locally).
  • The file is not being broadcast.

See Also

  • Playback Methods and Properties
  • Player6.AllowScan


Player6.CanSeek

This property retrieves a value indicating whether the current file has the ability to seek to a specific time.

Syntax

MediaPlayer.CanSeek

Possible Values

This property is a read-only Boolean.

Remarks

Seeking is accomplished by sliding the position indicator on the Windows Media Player trackbar or by setting either the CurrentMarker or CurrentPosition property.

If a media file has not been selected for the player, by setting the FileName property or calling the Open method, the value of this property will be false.

See Also

  • Playback Methods and Properties


Player6.CanSeekToMarkers

This property retrieves a value indicating whether markers in the file can be located with a seek operation.

Syntax

MediaPlayer.CanSeekToMarkers

Possible Values

This property is a read-only Boolean.

Remarks

You can seek to a marker only if the file contains markers and it is stored either locally or on a Microsoft® NetShow™ unicast server (not on an HTTP server or broadcast by using multicast routing).

Seeking to a marker is accomplished in Windows Media Player by choosing Go To from the Play menu, or in an application by setting the CurrentMarker property.

The value of this property is false if the FileName property is not set.

See Also

  • Playback Methods and Properties


Player6.CaptioningID

This property retrieves the name of the frame or control that displays captioning.

Syntax

MediaPlayer.CaptioningID

Possible Values

This property is a read-only String.


Player6.CCActive

This property specifies or retrieves a value indicating whether closed captioning is on or off.

Syntax

MediaPlayer.DVD.CCActive

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Closed captioning is on.
false | Default. Closed captioning is off.


Player6.ChannelDescription

This property retrieves the station description.

Syntax

MediaPlayer.ChannelDescription

Possible Values

This property is a read-only String.

Remarks

This property is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

This property only returns valid information for Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file.

See Also

  • Retrieving Presentation Information


Player6.ChannelName

This property retrieves the station name.

Syntax

MediaPlayer.ChannelName

Possible Values

This property is a read-only String.

Remarks

This property is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

This property only returns valid information for Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file.

See Also

  • Retrieving Presentation Information


Player6.ChannelURL

This property retrieves a value representing the URL of the station metafile.

Syntax

MediaPlayer.ChannelURL

Possible Values

This property is a read-only String.

Remarks

This property is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

This property only pertains to Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file. The station URL is the Uniform Resource Locator to the .nsc file. The station URL follows the syntax of typical URLs, except that it can also include the version number, which is separated from the rest of a URL with a # (pound sign). For example, a station URL might be:

http://example.microsoft.com/myfile.nsc#54

where 54 is the version desired. If the version of the .nsc file is on the local computer, a new .nsc file is not downloaded.

See Also

  • Retrieving Presentation Information


Player6.ClickToPlay

This property specifies or retrieves a value indicating whether the user can toggle playback on and off by clicking the video image.

Syntax

MediaPlayer.ClickToPlay

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Clicking the video image toggles playback.
false | Clicking the video image does not toggle playback.

Remarks

If the value of this property is true, clicking anywhere in the image display window toggles playback. (When a clip is playing, clicking the image pauses playback. When a clip is paused, clicking the image starts playback again.)

See Also

  • Capturing Keyboard and Mouse Events


Player6.ClientID

This property retrieves the unique ID of a client.

Syntax

MediaPlayer.ClientID

Possible Values

This property is a read-only String representing a Globally Unique Identifier (GUID).

Remarks

This property contains a GUID for each installation of the Windows Media Player control. This property can be used to identify individual players.


Player6.CodecCount

This property retrieves the number of installable codecs used by the current clip.

Syntax

MediaPlayer.CodecCount

Possible Values

This property is a read-only Long.

See Also

  • Player6.GetCodecDescription
  • Player6.GetCodecInstalled
  • Player6.GetCodecURL


Player6.ColorKey

This property specifies or retrieves the color key being used by the DVD playback.

Syntax

MediaPlayer.DVD.ColorKey

Possible Values

This property is a read/write ULONG indicating the color key. Specify as a hexadecimal value in the form 0xRRGGBB for Microsoft® JScript® and &HRRGGBB for Microsoft Visual Basic® Scripting Edition (VBScript).

Remarks

The color key refers to the destination color key being used by the overlay surface.

Applications should set the color key to an obscure color (some color which, in all probability, will not be present on the desktop). Overlay mixer filters will typically use an obscure color, but if the application knows that the specified color is part of some other content, then the application should change it.

For example, using JScript you can set the color key as follows.

MediaPlayer1.DVD.ColorKey = 0xffffff;

For more information, see Overlay Mixer in the Microsoft DirectShow™ Software Development Kit.


Player6.ConnectionSpeed

This property retrieves a the bandwidth selected during Windows Media Player setup.

Syntax

MediaPlayer.ConnnectionSpeed

Possible Values

This property is a read-only Long containing one of the following values.

Value | Description
14400 | 14.4K Modem
19200 | 19.2K Connection
28800 | 28.8K Modem
57600 | 56K Modem/ISDN
115200 | 112K Dual ISDN
1544000 | T1/LAN


Player6.ContactAddress

This property retrieves the station's contact address.

Syntax

MediaPlayer.ContactAddress

Possible Values

This property is a read-only String.

Remarks

This property only returns valid information for Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file.

See Also

  • Retrieving Presentation Information


Player6.ContactEmail

This property retrieves the station's e-mail address.

Syntax

MediaPlayer.ContactEmail

Possible Values

This property is a read-only String.

Remarks

This property only returns valid information for Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file.

See Also

  • Retrieving Presentation Information


Player6.ContactPhone

This property retrieves the station's contact telephone number.

Syntax

MediaPlayer.ContactPhone

Possible Values

This property is a read-only String.

Remarks

This property only returns valid information for Windows Media content being received from a station (defined IP address and port number). Station information is stored in a Microsoft® Windows Media™ Station (.nsc) file.

See Also

  • Retrieving Presentation Information


Player6.CreationDate

This property retrieves the date and time when the clip was created.

Syntax

MediaPlayer.CreationDate

Possible Values

This property is a read-only Date.

Remarks

This property returns valid data only if the FileName property is set.

See Also

  • Player6.GetMediaInfoString


Player6.CurrentAngle

This property specifies or retrieves a number identifying the current camera angle.

Syntax

MediaPlayer.DVD.CurrentAngle

Possible Values

This property is a read/write ULONG ranging from one to nine.

Remarks

Angles are interleaved video streams that contain the same scene shot from different camera angles.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.CurrentAudioStream

This property specifies or retrieves a value indicating the current audio stream.

Syntax

MediaPlayer.DVD.CurrentAudioStream

Possible Values

This property is a read/write ULONG ranging from zero to seven indicating the current audio stream, or 0xFFFFFFFF if no stream is selected.

Remarks

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.CurrentButton

This property retrieves the number of the currently selected button.

Syntax

MediaPlayer.DVD.CurrentButton

Possible Values

This property is a read-only ULONG.

Remarks

Button numbers range from 1 to 36. If buttons are not present, this property returns zero.


Player6.CurrentCCService

This property specifies or retrieves a value indicating the current closed captioning service.

Syntax

MediaPlayer.DVD.CurrentCCService

Possible Values

This property is a read/write ULONG containing one of the following values.

Value | Description
0 | None
1 | Default. Caption1
2 | Caption2
3 | Text1
4 | Text2
5 | Extended Data Services (XDS)


Player6.CurrentChapter

This property retrieves the chapter number currently being played.

Syntax

MediaPlayer.DVD.CurrentChapter

Possible Values

This property is a read-only ULONG.

Remarks

This property returns 0xFFFFFFFF if the title is not a One Sequential PGC title. In One_Sequential_PGC_Titles, each program is required to be a chapter and each title has only one PGC.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.CurrentDiscSide

This property retrieves the current disc side.

Syntax

MediaPlayer.DVD.CurrentDiscSide

Possible Values

This property is a read-only ULONG containing one of the following values.

Value | Description
1 | side A
2 | side B


Player6.CurrentDomain

This property retrieves the current DVD domain of the DVD player.

Syntax

MediaPlayer.DVD.CurrentDomain

Possible Values

This property is a read-only ULONG containing one of the following values.

Value | Constant | Domain | Description
1 | FP_DOM | FirstPlay | Doing default initialization of a DVD disc.
2 | VMGM_DOM | VideoManagerMenu | Displaying menus for whole disc.
3 | VTSM_DOM | VideoTitleSetMenu | Displaying menus for current title set.
4 | TT_DOM | Title | Displaying current title.
5 | STOP_DOM | Stop | Player is in stopped state.

Remarks

The domain indicates the state of the DVD player.


Player6.CurrentMarker

This property specifies or retrieves the current marker number.

Syntax

MediaPlayer.CurrentMarker

Possible Values

This property is a read/write Long with a default value of zero.

Remarks

Before attempting to set this property, determine whether a file has markers and their number by using the MarkerCount property. If a file has no markers, setting CurrentMarker to anything but zero results in an error. Setting CurrentMarker to a number higher than MarkerCount also results in an error.

CurrentMarker always returns the current or last marker, which means the actual file position can be either at the current marker or before the next marker. Markers are numbered beginning at 1, so if a file has markers, you can set CurrentMarker to zero to change the file position to zero.

Before FileName is set, CurrentMarker returns zero.

See Also

  • Playback Methods and Properties


Player6.CurrentPosition

This property specifies or retrieves the clip's current position, in seconds.

Syntax

MediaPlayer.CurrentPosition

Possible Values

This property is a read/write Double with no default value.

Remarks

The value of this property is a new position within the clip, in seconds. This property is only valid for playback of local content.

Setting this property at run time is similar to performing a seek operation, and changes the position to the specified point in the clip. The new value must be within the range specified by the SelectionStart and SelectionEnd properties.

Before attempting to set this property, determine the length of the file in seconds by retrieving the value of the Duration property.

Before the FileName property is set, CurrentPosition returns -1 (minus one).

The current position value displayed by Windows Media Player can represent either seconds or frames. The DisplayMode property determines which units are shown.

Example

This example shows how to use the CurrentPosition property to rewind a clip after it has been stopped:

MediaPlayer1.Stop
MediaPlayer1.CurrentPosition = 0

See Also

  • Playback Methods and Properties


Player6.CurrentSubpictureStream

This property specifies or retrieves a value indicating the current subpicture stream.

Syntax

MediaPlayer.DVD.CurrentSubpictureStream

Possible Values

This property is a read/write ULONG containing one of the following values.

Value | Description
0-31 | Indicates that the stream is valid.
63 | Indicates that there is no subpicture stream.

Remarks

This property has a default value of 63 when there are no subpictures available. If subpictures are available, the default value is 0.

Subpictures are encoded graphics, such as subtitles or menus, that can be displayed over the top of the video.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain
  • Player6.EC_DVD_SUBPICTURE_STREAM_CHANGE
  • Player6.GetSubpictureLanguage
  • Player6.SubpictureOn
  • Player6.SubpictureStreamsAvailable


Player6.CurrentTime

This property retrieves the current playback time.

Syntax

MediaPlayer.DVD.CurrentTime

Possible Values

This property is a read-only BSTR.

Remarks

This property resolves to a string indicating the current playback time for the current title in the form of "hh:mm:ss:ff" (hours, minutes, seconds, and frames, each two digits). Frames per second for the DVD title is either 25 or 30 and is defined by the read-only FramesPerSecond property.

This property contains a NULL string unless the current domain is TT_DOM.

See Also

  • Player6.CurrentDomain


Player6.CurrentTitle

This property retrieves the number of the title currently being played.

Syntax

MediaPlayer.DVD.CurrentTitle

Possible Values

This property is a read-only ULONG.

Remarks

The current title is the Title Track Number (TTN) for the whole disc, not the Title Set_Title Track Number (VTS_TTN), which is the title number with respect to just a current Video Title Set (VTS).

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.CurrentVolume

This property retrieves the volume number for the current root directory.

Syntax

MediaPlayer.DVD.CurrentVolume

Possible Values

This property is a read-only ULONG.


Player6.CursorType

This property specifies or retrieves the cursor type.

Syntax

MediaPlayer.CursorType

Possible Values

This property is a read/write Long with a default value of zero. See Remarks for more information.

Remarks

You can specify the cursor's icon when it is over the Windows Media Player control by setting this property to any of the stock cursor values from the Microsoft Platform SDK.

Name | Value | Description
IDC_APPSTARTING | 32650 | Standard arrow and small hourglass
IDC_ARROW | 32512 | Standard arrow
IDC_CROSS | 32515 | Crosshair
IDC_IBEAM | 32513 | Text I-beam
IDC_NO | 32648 | Slashed circle
IDC_SIZEALL | 32646 | Four-pointed arrow
IDC_SIZENESW | 32643 | Double-pointed arrow pointing northeast and southwest
IDC_SIZENS | 32645 | Double-pointed arrow pointing north and south
IDC_SIZENWSE | 32642 | Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE | 32644 | Double-pointed arrow pointing west and east
IDC_UPARROW | 32516 | Vertical arrow
IDC_WAIT | 32514 | Hourglass
IDC_HAND | 1 | Hand with pointing index finger

The default value of this property is zero, which represents a hand with a pointing index finger if no file is loaded, and a standard arrow if a file is loaded.

If the ClickToPlay property is true, the arrow changes to a hand when it is over the image display window to indicate that the user can click the mouse.

The CursorType property is disabled in full-screen mode.

See Also

  • Player6.ClickToPlay


Player6.DefaultFrame

This property specifies or retrieves a value representing the default target HTTP frame.

Syntax

MediaPlayer.DefaultFrame

Possible Values

This property is a read/write String.

Remarks

This property specifies which browser frame displays a new location when a URL-type ScriptCommand event occurs. If the ScriptCommand event specifies the frame, however, the property is ignored.

See Also

  • Player6.BaseURL
  • Player6.InvokeURLs
  • Player6.ScriptCommand
  • Processing Embedded Script Commands


Player6.DisplayBackColor

This property specifies or retrieves the background color of the display panel.

Syntax

MediaPlayer.DisplayBackColor

Possible Values

This property is a read/write Long with a default value of zero (black).

Remarks

You can specify the background color by using normal RGB colors or system default colors.

Normal RGB colors are colors specified by using the color palette or by using the Microsoft® Visual Basic® RGB or QBColor functions in code.

System default colors are colors specified by system color constants listed in the object library of the object browser. The Microsoft Windows® operating environment substitutes the user's choices as specified in the control panel settings.

The valid range for a normal RGB color is zero to 0xFFFFFF. The high byte of a number in this range equals 0; the lower 3 bytes, from most to least significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (0xFF). If the high byte is not zero, Visual Basic uses the system colors, as defined in the user's control panel settings and by constants listed in the object library of the object browser.

See Also

  • Player6.DisplayForeColor


Player6.DisplayForeColor

This property specifies or retrieves the foreground color of the display panel.

Syntax

MediaPlayer.DisplayForeColor

Possible Values

This property is read/write Long with a default value of 0xFFFFFF (white).

Remarks

You can specify the foreground color by using normal RGB colors or system default colors.

Normal RGB colors are colors specified by using the color palette or by using the Microsoft® Visual Basic® RGB or QBColor functions in code.

System default colors are colors specified by system color constants listed in the object library of the object browser. The Microsoft Windows® operating environment substitutes the user's choices as specified in the control panel settings.

The valid range for a normal RGB color is 0 to 16777215 (0xFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from most to least significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (0xFF). If the high byte is not zero, Visual Basic uses the system colors, as defined in the user's control panel settings and by constants listed in the object library of the object browser.

See Also

  • Player6.DisplayBackColor


Player6.DisplayMode

This property specifies or retrieves a value indicating whether the status bar displays the current position in seconds or frames.

Syntax

MediaPlayer.DisplayMode

Possible Values

This property is a read/write Integer containing one of the following values.

Value | Description
0 | Default. Displays the current position in seconds.
1 | Displays the current position in frames.

Remarks

This property is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

This property is valid only for local-playback content.

See Also

  • Player6.DisplayModeChange
  • Player6.ShowStatusBar


Player6.DisplaySize

This property specifies or retrieves the size of the image display window.

Syntax

MediaPlayer.DisplaySize

Possible Values

This property is read/write Long containing one of the following values.

Value | Visual Basic constant | Description
0 | mpDefaultSize | Same size as the source image.
1 | mpHalfSize | Width and height are one-half of the source image dimensions, resulting in an image that is one-fourth the original size.
2 | mpDoubleSize | Double the dimensions of the source image.
3 | mpFullScreen | Size of the entire screen.
4 | mpFitToSize | Size specified at design time.
5 | mpOneSixteenthScreen | One-sixteenth the size of the screen.
6 | mpOneFourthScreen | One-quarter the size of the screen.
7 | mpOneHalfScreen | Half the size of the screen.

Remarks

This property can only be set if the value of the AllowChangeDisplaySize property is true.

If the value of the AutoSize property is true, Windows Media Player automatically changes its size to accommodate the video image at the size specified by the DisplaySize property. Otherwise, Windows Media Player does not resize, and the image is centered in the video display panel.

If AutoSize is true and the DisplaySize property is set to 4 (mpFitToSize), the video image displays at the default size.

Note For DVD playback, if this property equals 5, the image display window displays at half the size of the screen; if it equals 6, the window displays at one-sixteenth the size of the screen; and if it equals 7, the window displays at one-quarter the size of the screen. For values of 0 through 4, the image display window resizes according to the values show in the above table.

See Also

  • Customizing the User Interface
  • Player6.AllowChangeDisplaySize
  • Player6.AutoSize
  • Player6.EnableFullScreenControls


Player6.Duration

This property retrieves the length of the clip, in seconds.

Syntax

MediaPlayer.Duration

Possible Values

This property is a read-only Double.

Remarks

The IsDurationValid property specifies whether the Duration property returns a valid value. If the FileName property is not set, the Duration property returns zero.

See Also

  • Player6.IsDurationValid
  • Retrieving Presentation Information
  • Using Playlists


Player6.DVD

This property retrieves the Windows Media Player control DVD interface.

Syntax

MediaPlayer.DVD.Property
MediaPlayer.DVD.Method

Remarks

DVD-specific properties and methods use the DVD property to return the IMediaPlayerDvd interface.


Player6.EnableContextMenu

This property specifies or retrieves a value indicating whether the context menu appears when the user clicks the right mouse button.

Syntax

MediaPlayer.EnableContextMenu

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The context menu is enabled.
false | The context menu is disabled.

Remarks

If the value of this property is true, right-clicking the mouse anywhere on the Windows Media Player control opens the context (shortcut) menu.

The context menu contains options usually available to the user as buttons (Play/Pause, Stop, Properties, and so on). If any of these buttons is disabled, the function associated with that button is also disabled on the context menu.

See Also

  • Capturing Keyboard and Mouse Events
  • Customizing the User Interface


Player6.Enabled

This property specifies or retrieves a value indicating whether the Windows Media Player control is enabled.

Syntax

MediaPlayer.Enabled

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The Windows Media Player control is enabled.
false | The Windows Media Player control is disabled.

Remarks

This property is identical to the standard Microsoft Visual Basic® Enabled property.

A disabled Windows Media Player control remains visible if it was already visible, and continues to play if it was already playing. However, the commands or menus do not respond to user input.

Disabling a control at design time is useful if you want to control the media stream from an external source, such as a custom group of controls on a Web page, instead of from the built-in control panel.


Player6.EnableFullScreenControls

This property specifies or retrieves a value indicating whether Windows Media Player displays controls in full-screen mode.

Syntax

MediaPlayer.EnableFullScreenControls

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Full-screen controls are enabled.
false | Full-screen controls are disabled.

Remarks

When the value of this property is true, Windows Media Player displays the control bar at the bottom of the screen when Windows Media Player expands to full-screen mode. The control bar disappears after a few moments; however, it is redisplayed if the user positions the cursor at the bottom of the screen.

See Also

  • Player6.DisplaySize


Player6.EnablePositionControls

This property specifies or retrieves a value indicating whether the position controls are enabled on the control bar.

Syntax

MediaPlayer.EnablePositionControls

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Position controls are enabled.
false | Position controls are disabled.

Remarks

Position controls include the following:

Skip Ahead

Skip Back

Fast Forward

Fast Reverse

Preview Mode

See Also

  • Player6.ShowControls
  • Player6.ShowPositionControls


Player6.EnableTracker

This property specifies or retrieves a value indicating whether the trackbar control is enabled.

Syntax

MediaPlayer.EnableTracker

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The trackbar control is enabled.
false | The trackbar control is disabled.

Remarks

The Windows Media Player control displays the trackbar only when the ShowControls and ShowTracker properties are both true.

See Also

  • Player6.ShowControls
  • Player6.ShowTracker


Player6.EntryCount

This property retrieves the number of entries contained in the current Windows Media metafile.

Syntax

MediaPlayer.EntryCount

Possible Values

This property is a read-only Integer indicating the number of ENTRY elements in the current Windows Media metafile.

Remarks

Note This scripting property is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.

See Also

  • Player6.GetCurrentEntry
  • Player6.GetMediaParameter
  • Player6.GetMediaParameterName
  • Player6.SetCurrentEntry


Player6.ErrorCode

This property retrieves the current error code.

Syntax

MediaPlayer.ErrorCode

Possible Values

This property is a read-only Long.

See Also

  • Error Handling
  • Player6.ErrorCorrection
  • Player6.ErrorDescription
  • Player6.HasError
  • Player6.SendErrorEvents


Player6.ErrorCorrection

This property retrieves the error correction type of the current clip.

Syntax

MediaPlayer.ErrorCorrection

Possible Values

This property is a read-only String containing one of the following values.

Value | Description
Standard | Standard error correction.
None | No error correction.

Remarks

This property returns an empty string if the FileName property is not set.

See Also

  • Error Handling
  • Player6.ErrorCode
  • Player6.ErrorDescription
  • Player6.HasError
  • Player6.SendErrorEvents


Player6.ErrorDescription

This property retrieves a description of the current error state.

Syntax

MediaPlayer.ErrorDescription

Possible Values

This property is a read-only String with no default value.

See Also

  • Error Handling
  • Player6.ErrorCode
  • Player6.ErrorCorrection
  • Player6.HasError
  • Player6.SendErrorEvents


Player6.FileName

This property specifies or retrieves the name of the clip to play.

Syntax

MediaPlayer.FileName

Possible Values

This property is a read/write String with a default value of "" (the empty string).

Remarks

If the value of the AutoStart property is true, file playback begins automatically whenever you set the FileName property. If you set both AutoStart and FileName at design time, the Windows Media Player control begins playing the file when it is loaded.

Setting this property is a synchronous operation; control does not return to the application until after the file has completed the open process. The Open method performs the same operation asynchronously.

To use compact disc audio with your CD-ROM drive as input to the Windows Media Player control, set this property to cdaudio: (with the trailing ":"). For more information, see Compact Disc Audio Playback.

To use digital video disc (DVD) as input, set this property to dvd: (with the trailing ":"). For more information, see Viewing DVD in a Web Page.

See Also

  • Playback Methods and Properties
  • Player6.AutoStart
  • Player6.Open
  • Processing Embedded Script Commands


Player6.FramesPerSecond

This property retrieves a value indicating the number of frames per second used by the DVD title.

Syntax

MediaPlayer.DVD.FramesPerSecond

Possible Values

This property is a read-only ULONG containing one of the following values.

Value | Description
25 | DVD title runs 25 frames per second (PAL).
30 | DVD title runs 30 frames per second (NTSC).

Remarks

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.HasError

This property retrieves a value indicating whether the Windows Media Player control currently has an error.

Syntax

MediaPlayer.HasError

Possible Values

This property is a read-only Boolean.

Remarks

If the value of this property is true, you can retrieve the ErrorCode and ErrorDescription properties to determine the nature of the error.

See Also

  • Error Handling
  • Player6.ErrorCode
  • Player6.ErrorDescription


Player6.HasMultipleItems

This property retrieves a value indicating whether the current Windows Media metafile contains multiple ENTRY items.

Syntax

MediaPlayer.HasMultipleItems

Possible Values

This property is a read-only Boolean.

See Also

  • Player6.CanPreview
  • Player6.PreviewMode


Player6.ImageSourceHeight

This property retrieves the original image height of the current clip, in pixels.

Syntax

MediaPlayer.ImageSourceHeight

Possible Values

This property is a read-only Long.

Remarks

If the FileName property is not set, this property returns zero.

See Also

  • Player6.ImageSourceWidth
  • Retrieving Presentation Information


Player6.ImageSourceWidth

This property retrieves the original image width of the current clip, in pixels.

Syntax

MediaPlayer.ImageSourceWidth

Possible Values

This property is a read-only Long.

Remarks

If the FileName property is not set, this property returns zero.

See Also

  • Player6.ImageSourceHeight
  • Retrieving Presentation Information


Player6.InvokeURLs

This property specifies or retrieves a value indicating whether the Windows Media Player control automatically invokes URLs in a browser (URL flipping).

Syntax

MediaPlayer.InvokeURLs

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. URL flipping is enabled.
false | URL flipping is disabled.

Remarks

Windows Media files can contain Uniform Resource Locators (URLs). When a URL is sent to the Windows Media Player control, it is passed first to the ScriptCommand event, regardless of the value of the InvokeURLs property. After ScriptCommand exits, the value of InvokeURLs determines whether the Windows Media Player control starts the default browser and loads the URL. You can selectively display URLs by checking them in ScriptCommand and setting InvokeURLs as desired. For more information, see the ScriptCommand event.

See Also

  • Player6.ScriptCommand
  • Processing Embedded Script Commands


Player6.IsBroadcast

This property retrieves a value indicating whether the source is broadcast.

Syntax

MediaPlayer.IsBroadcast

Possible Values

This property is a read-only Boolean.

Remarks

Viewing a broadcast clip is analogous to viewing a television program. Functions such as pause, fast-forward, and rewind are not available.


Player6.IsDurationValid

This property retrieves a value indicating whether the value of the Duration property is valid.

Syntax

MediaPlayer.IsDurationValid

Possible Values

This property is a read-only Boolean.

Remarks

During some broadcasts (typically live events) the duration of the presentation is unknown. If the duration cannot be determined, the value of this property is false.

See Also

  • Player6.Duration
  • Retrieving Presentation Information


Player6.Language

This property specifies or retrieves a value indicating the current locale used for national language support.

Syntax

MediaPlayer.Language

Possible Values

This property is a read/write Long that corresponds to an LCID identifying a locale for national language support.


Player6.LostPackets

This property retrieves the number of packets lost during transmission of the stream.

Syntax

MediaPlayer.LostPackets

Possible Values

This property is a read-only Long.

Remarks

This property is valid only for streaming media. Packets may be lost for a number of reasons, such as the type and quality of the network connection.

Each time playback stops and restarts, this property resets to zero. It does not reset if playback pauses and restarts. This property returns valid information only during run time, and only if the FileName property is set.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.ReceivedPackets
  • Player6.ReceptionQuality
  • Player6.RecoveredPackets


Player6.MarkerCount

This property retrieves the number of markers in the current clip.

Syntax

MediaPlayer.MarkerCount

Possible Values

This property is a read-only Long.

Remarks

This property returns zero if a file has no markers or the FileName property is not set. Marker numbers start at 1.

See Also

  • Playback Methods and Properties
  • Player6.GetMarkerName
  • Player6.GetMarkerTime


Player6.Mute

This property specifies or retrieves the current mute state of the Windows Media Player control.

Syntax

MediaPlayer.Mute

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Volume is muted.
false | Default. Volume is not muted.

See Also

  • Playback Methods and Properties


Player6.OpenState

This property retrieves the state of the content source.

Syntax

MediaPlayer.OpenState

Possible Values

This property is a read-only Long containing one of the following values.

Value | Visual Basic constant | Description
0 | nsClosed | Content file is closed.
1 | nsLoadingASX | Loading a Windows Media metafile.
2 | nsLoadingNSC | Loading an .nsc station file.
3 | nsLocating | Locating the server.
4 | nsConnecting | Connecting to the server.
5 | nsOpening | Opening or listening for the stream.
6 | nsOpen | Content file is open.

Remarks

Retrieve this property to determine the status of a request to open a clip.

If the value of the SendOpenStateChangeEvents property is true, the Windows Media Player control fires an OpenStateChange event each time the OpenState property changes.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.OpenStateChange
  • Player6.SendOpenStateChangeEvents


Player6.PlayCount

This property specifies or retrieves the number of times a clip plays.

Syntax

MediaPlayer.PlayCount

Possible Values

This property is a read/write Long with a default value of 1.

Remarks

If the value of this property is zero, the clip plays repeatedly, restarting as soon as it reaches the end.

See Also

  • Playback Methods and Properties
  • Player6.AutoStart


Player6.PlayState

This property retrieves a value indicating the state of the Windows Media Player operation.

Syntax

MediaPlayer.PlayState

Possible Values

This property is a read-only Long containing one of the following values.

Value | Visual Basic constant | Description
0 | mpStopped | Playback is stopped.
1 | mpPaused | Playback is paused.
2 | mpPlaying | Stream is playing.
3 | mpWaiting | Waiting for stream to begin.
4 | mpScanForward | Stream is scanning forward.
5 | mpScanReverse | Stream is scanning in reverse.
6 | mpSkipForward | Skipping to next.
7 | mpSkipReverse | Skipping to previous.
8 | mpClosed | Stream is not open.

Remarks

Retrieve this property to determine the status of an open clip.

If the value of the SendPlayStateChangeEvents property is true, Windows Media Player control fires a PlayStateChange event each time the PlayState property changes.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.PlayStateChange
  • Player6.SendPlayStateChangeEvents


Player6.PreviewMode

This property specifies or retrieves a value indicating whether Windows Media Player is in preview mode.

Syntax

MediaPlayer.PreviewMode

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Windows Media Player is in preview mode.
false | Default. Windows Media Player is not in preview mode.

Remarks

In preview mode, the Windows Media Player control plays a short preview of each title in a playlist. You can only set this property to true if the value of the CanPreview property is also true.

See Also

  • Player6.CanPreview
  • Using Playlists


Player6.Rate

This property specifies or retrieves the playback rate of the clip.

Syntax

MediaPlayer.Rate

Possible Values

This property is a read/write Double with a default value of 1.0.

Remarks

This property acts as a multiplier value that allows you to play the clip at a faster or slower rate. The default value of 1.0 indicates the authored speed. Note that the audio track becomes difficult to understand at rates lower than 0.5 or higher than 1.5. A playback rate of 2 equates to twice the normal playback speed.

Other considerations apply as well, depending on media type:

Windows Media and video on demand (VOD): Optimal values for this property are from 1 to 10 or from –1 to –10. Values with an absolute magnitude greater than 10 are allowed, but not very meaningful. Audio plays only when the value is 1. A Windows Media or VOD file must be stopped and the AllowScan property must be true before you can set the Rate property. Negative values for this property indicate reversed playback. Video on demand (VOD) and Windows Media files both support the Rate property; however, Windows Media content can use the Rate property only if the following conditions are all true:

  • The file is indexed.
  • The file is playing from a Microsoft® NetShow™ unicast server (not playing locally).
  • The file is not being broadcast.

Other Media Types: This property can range from 0 to 9. Negative values are not allowed. Values less than 1 represent slow motion. Values above 9 are allowed, but not very meaningful.

See Also

  • Playback Methods and Properties
  • Player6.AllowScan
  • Player6.CanScan


Player6.ReadyState

This property retrieves the state of readiness of the Windows Media Player control.

Syntax

MediaPlayer.ReadyState

Possible Values

This property is a read-only Long containing one of the following values.

Value | Visual Basic constant | Description
0 | mpReadyStateUninitialized | The FileName property has not been initialized.
1 | mpReadyStateLoading | Windows Media Player control is asynchronously loading a file.
3 | mpReadyStateInteractive | Windows Media Player control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
4 | mpReadyStateComplete | All data has been downloaded.

Remarks

Windows Media Player control changes this property at run time, and passes its value as a parameter to the ReadyStateChange event.

The Play method does not work until the value of ReadyState is 3 (mpReadyStateInteractive) or 4 (mpReadyStateComplete).

See Also

  • Player6.ReadyStateChange


Player6.ReceivedPackets

This property retrieves the number of packets received.

Syntax

MediaPlayer.ReceivedPackets

Possible Values

This property is a read-only Long.

Remarks

Each time playback stops and restarts, this property resets to zero. It does not reset if file playback is paused.

This property returns valid information only during run time and only if the FileName property is set.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.LostPackets
  • Player6.ReceptionQuality
  • Player6.RecoveredPackets


Player6.ReceptionQuality

This property retrieves the percentage of packets received in the last 30 seconds.

Syntax

MediaPlayer.ReceptionQuality

Possible Values

This property is a read-only Long.

Remarks

Every second, the Windows Media Player control monitors the number of packets received, lost, and recovered during streaming. The value of this property represents the percentage of packets not lost over the past 30 seconds.

Each time file playback stops and restarts, this property resets to zero. It does not reset if file playback is paused.

This property returns valid information only during run time and only if the FileName property is set.

See also

  • Monitoring Stream Status and Network Reception
  • Player6.LostPackets
  • Player6.ReceivedPackets
  • Player6.RecoveredPackets


Player6.RecoveredPackets

This property retrieves the number of packets recovered.

Syntax

MediaPlayer.RecoveredPackets

Possible Values

This property is a read-only Long.

Remarks

Each time file playback stops and restarts, this property resets to zero. It does not reset if file playback is paused.

This property returns valid information only during run time and only if the FileName property is set.

See Also

  • Player6.LostPackets
  • Player6.ReceivedPackets
  • Player6.ReceptionQuality


Player6.Root

This property specifies or retrieves a value indicating the directory that contains the DVD volume.

Syntax

MediaPlayer.DVD.Root

Possible Values

This property is a read/write BSTR.

Remarks

If you have not set the root directory before calling the TitlePlay method, the first drive starting from C: containing a VIDEO_TS directory in the top level directory will be used as the root.

The current domain must be STOP_DOM when you set this property.

See Also

  • Player6.CurrentDomain


Player6.SAMIFileName

This property specifies or retrieves the name of the file that contains the closed captioning information.

Syntax

MediaPlayer.SAMIFileName

Possible Values

This property is a read/write String.

Remarks

The Synchronized Accessible Media Interchange (SAMI) file must use an .smi or .sami file extension.

See Also

  • Closed Captioning
  • Player6.CaptioningID
  • Player6.SAMIStyle
  • Player6.ShowCaptioning


Player6.SAMILang

This property specifies or retrieves a value indicating the language displayed for closed captioning.

Syntax

MediaPlayer.SAMILang

Possible Values

This property is a read/write String. If no language is specified, the default behavior is for closed captioning to display the first language defined in the Synchronized Accessible Media Interchange (SAMI) file.

Remarks

This property supports only English when the Windows Media Player control is embedded in a Web page viewed with Netscape Navigator.

A SAMI file can contain text for one or many languages. The languages available for closed captioning are defined between the <STYLE> and </STYLE> tags in the SAMI file. A language can be specified by any unique alphanumeric string that is preceded by a period. For example, .ENUSCC could be used to define US English.

See Also

  • Closed Captioning
  • Player6.CaptioningID
  • Player6.SAMIStyle
  • Player6.ShowCaptioning


Player6.SAMIStyle

This property specifies or retrieves a value representing the closed captioning style.

Syntax

MediaPlayer.SAMIStyle

Possible Values

This property is a read/write String. If no style is specified, the default behavior is for closed captioning to use the first style defined in the Synchronized Accessible Media Interchange (SAMI) file.

Remarks

This property is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

A SAMI file can contain several format style definitions. SAMI styles are defined between the <STYLE> and </STYLE> tags in the SAMI file. A style can be defined by any text string preceded by a pound sign (#). For example, #BigFont can be used to specify that closed captioning should display in a larger font size.

See Also

  • Closed Captioning
  • Player6.CaptioningID
  • Player6.SAMILang
  • Player6.ShowCaptioning


Player6.SelectionEnd

This property specifies or retrieves the time within the current clip at which playback will stop.

Syntax

MediaPlayer.SelectionEnd

Possible Values

This property is a read/write Double. The default value is the length of the clip.

Remarks

This property cannot be set or retrieved until the ReadyState property has a value of 4 (mpReadyStateComplete).

Note When Windows Media Player is operating in preview mode, this property reflects the length of time each clip will be previewed.

See Also

  • Player6.PreviewMode
  • Player6.ReadyState
  • Player6.SelectionStart


Player6.SelectionStart

This property specifies or retrieves the time within the current clip at which playback will begin.

Syntax

MediaPlayer.SelectionStart

Possible Values

This property is a read/write Double indicating the start position in seconds relative to the beginning of the presentation. It has a default value of zero (the beginning of the clip).

Remarks

This property cannot be set or returned until the ReadyState property has a value of 4 (mpReadyStateComplete).

See Also

  • Player6.ReadyState
  • Player6.SelectionEnd


Player6.SendErrorEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends error events.

Syntax

MediaPlayer.SendErrorEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Error events are enabled.
false | Error events are disabled.

Remarks

When error events are enabled, error message boxes are disabled, and vice versa.

If the value of this property is false and an error occurs, Windows Media Player displays a dialog box with a description of the error. If this property is true, error dialog boxes are disabled, and the application must handle error conditions.

See Also

  • Error Handling
  • Player6.ErrorCode
  • Player6.ErrorCorrection
  • Player6.ErrorDescription
  • Player6.HasError


Player6.SendKeyboardEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends keyboard events.

Syntax

MediaPlayer.SendKeyboardEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Keyboard events are enabled.
false | Default. Keyboard events are disabled.

Remarks

The Windows Media Player control fires keyboard events only when the value of this property is true and Windows Media Player control has focus.

Note Enable keyboard events only if you need to use them, because they incur a slight loss in performance.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.KeyDown
  • Player6.KeyPress
  • Player6.KeyUp


Player6.SendMouseClickEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends mouse click events.

Syntax

MediaPlayer.SendMouseClickEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Mouse click events are enabled.
false | Default. Mouse click events are disabled.

Remarks

The Windows Media Player control fires mouse click events only when this property is true.

Note Enable mouse click events only if you need to use them, because they incur a slight loss in performance.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.Click
  • Player6.DblClick
  • Player6.MouseDown
  • Player6.MouseUp


Player6.SendMouseMoveEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends mouse move events.

Syntax

MediaPlayer.SendMouseMoveEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Mouse move events are enabled.
false | Default. Mouse move events are disabled.

Remarks

The Windows Media Player control fires mouse move events only when this property is true and the Windows Media Player control has focus.

Note Enable mouse move events only if you need to use them, because they incur a slight performance cost.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.MouseMove


Player6.SendOpenStateChangeEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends open state change events.

Syntax

MediaPlayer.SendOpenStateChangeEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Open state change events are enabled.
false | Open state change events are disabled.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.OpenState
  • Player6.OpenStateChange


Player6.SendPlayStateChangeEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends play state change events.

Syntax

MediaPlayer.SendPlayStateChangeEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Play state change events are enabled.
false | Play state change events are disabled.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.PlayState
  • Player6.PlayStateChange


Player6.SendWarningEvents

This property specifies or retrieves a value indicating whether the Windows Media Player control sends warning events.

Syntax

MediaPlayer.SendWarningEvents

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Warning events are enabled.
false | Warning events are disabled.

See Also

  • Player6.Warning


Player6.ShowAudioControls

This property specifies or retrieves a value indicating whether the audio controls appear on the control bar.

Syntax

MediaPlayer.ShowAudioControls

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. Audio controls appear on the control bar.
false | Audio controls do not appear on the control bar.

Remarks

Audio controls consist of a volume slider bar and a speaker icon that acts as a mute button. This property specifies whether the audio controls appear on the control bar. The control bar itself is displayed or hidden by setting the ShowControls property. This property can affect the overall width of Windows Media Player. In some cases, the width of the control bar defines the overall width of Windows Media Player. Adding audio controls increases the width of the control bar.

See Also

  • Customizing the User Interface
  • Playback Methods and Properties
  • Player6.ShowControls


Player6.ShowCaptioning

This property specifies or retrieves a value indicating whether the closed caption area is visible and closed captioning is enabled.

Syntax

MediaPlayer.ShowCaptioning

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The closed caption area is visible and closed captioning is enabled.
false | Default. The closed caption area is not visible and closed captioning is disabled.

Remarks

If the clip has been captioned, a CC icon appears in the status bar.

See Also

  • Closed Captioning
  • Customizing the User Interface
  • Player6.CaptioningID


Player6.ShowControls

This property specifies or retrieves a value indicating whether the control bar is visible.

Syntax

MediaPlayer.ShowControls

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The control bar is visible.
false | The control bar is not visible.

Remarks

The control bar contains buttons for starting, stopping, and pausing playback. Optionally, you can add or remove position controls, audio controls, and the trackbar by setting the ShowPositionControls, ShowAudioControls, and ShowTracker properties, respectively.

This property can affect the overall width of Windows Media Player. In some cases the width of the control bar defines the overall width of Windows Media Player. Adding position and audio controls increases the width of the control bar.

See Also

  • Customizing the User Interface
  • Player6.ShowAudioControls
  • Player6.ShowPositionControls
  • Player6.ShowTracker
  • Using Playlists


Player6.ShowDisplay

This property specifies or retrieves a value indicating whether the display panel is visible.

Syntax

MediaPlayer.ShowDisplay

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The display panel is visible.
false | Default. The display panel is not visible.

See Also

  • Customizing the User Interface
  • Player6.ShowControls


Player6.ShowGotoBar

This property specifies or retrieves a value indicating whether the Go To bar is visible.

Syntax

MediaPlayer.ShowGotoBar

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The Go To bar is visible.
false | Default. The Go To bar is not visible.

Remarks

The Go To bar provides a list of markers in the clip being played. The user can seek to any marker by clicking on the list.

See Also

  • Customizing the User Interface
  • Player6.ShowControls


Player6.ShowPositionControls

This property specifies or retrieves a value indicating whether the position controls appear on the control bar.

Syntax

MediaPlayer.ShowPositionControls

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The position controls appear on the control bar.
false | The position controls do not appear on the control bar.

Remarks

The position controls consist of five buttons:

  • Skip Back: Jumps to the previous clip in the playlist.
  • Rewind: Scans rapidly backward through the current clip.
  • Fast Forward: Scans rapidly forward through the current clip.
  • Skip Forward: Jumps to the next clip in the playlist.
  • Preview: Plays a preview of each clip in the playlist.

This property specifies whether the position controls appear on the control bar. The control bar itself is displayed or hidden by setting the ShowControls property.

This property can affect the overall width of Windows Media Player. In some cases the width of the control bar defines the overall width of Windows Media Player. Adding position controls increases the width of the control bar.

Important This property specifies the visibility of the position controls. The EnablePositionControls property determines whether the position controls are active or disabled.

See Also

  • Customizing the User Interface
  • Player6.EnablePositionControls
  • Player6.ShowControls
  • Using Playlists


Player6.ShowStatusBar

This property specifies or retrieves a value indicating whether the status bar is visible.

Syntax

MediaPlayer.ShowStatusBar

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The status bar is visible.
false | Default. The status bar is not visible.

Remarks

The status bar displays status messages, including errors, and the elapsed play time and duration of the presentation.

See Also

  • Customizing the User Interface


Player6.ShowTracker

This property specifies or retrieves a value indicating whether the trackbar is visible.

Syntax

MediaPlayer.ShowTracker

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | Default. The trackbar is visible.
false | The trackbar is not visible.

Remarks

The trackbar is a slider control that indicates the progress of the clip currently playing. Users can seek to any position in the clip by dragging the progress indicator on the trackbar.

The trackbar is displayed only if the control bar is visible (that is, when the value of the ShowControls property is true).

Important This property specifies the visibility of the trackbar. The EnableTracker property determines whether the trackbar is active or disabled.

See Also

  • Customizing the User Interface
  • Player6.EnableTracker
  • Player6.ShowControls


Player6.SourceLink

This property retrieves the path to the current clip.

Syntax

MediaPlayer.SourceLink

Possible Values

This property is a read-only String.

Remarks

Multiple clips can appear in one Windows Media metafile. Retrieve this property to determine where the current clip file resides.

This property returns valid information only if the FileName property has been set.


Player6.SourceProtocol

This property retrieves a value indicating the protocol used to receive data.

Syntax

MediaPlayer.SourceProtocol

Possible Values

This property is a read-only Long containing one of the following values.

Value | Visual Basic constant | Description
1 | nsMulticast | Multicasting with no control connection.
2 | nsMulticastPlus | Multicasting with control connection.
3 | nsUDP | User Datagram Protocol.
4 | nsTCP | Transmission Control Protocol.
5 | nsDistribution | MSBD protocol. Typically used to connect directly to the encoder for test purposes.
6 | nsHTTP | Hypertext Transfer Protocol.
7 | nsFile | Local file playback.

See Also

  • Player6.SourceLink


Player6.StreamCount

This property retrieves the number of media streams in the current clip.

Syntax

MediaPlayer.StreamCount

Possible Values

This property is a read-only Long.

See Also

  • Player6.GetStreamGroup
  • Player6.GetStreamName
  • Player6.GetStreamSelected
  • Player6.StreamSelect


Player6.SubpictureOn

This property specifies or retrieves a value indicating whether the subpicture is displayed.

Syntax

MediaPlayer.DVD.SubpictureOn

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The subpicture is displayed
false | The subpicture is not displayed

Remarks

Subpictures are encoded graphics, such as subtitles or menus, that can be displayed over the top of the video. Subpicture streams authored as forcefully activated streams will be displayed even if this property is set to false.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain
  • Player6.CurrentSubpictureStream
  • Player6.EC_DVD_SUBPICTURE_STREAM_CHANGE
  • Player6.GetSubpictureLanguage
  • Player6.SubpictureStreamsAvailable


Player6.SubpictureStreamsAvailable

This property retrieves the number of available subpicture streams.

Syntax

MediaPlayer.DVD.SubpictureStreamsAvailable

Possible Values

This property is a read-only ULONG.

Remarks

Subpictures are encoded graphics, such as subtitles or menus, that can be displayed over the top of the video. DVD has a maximum of 32 subpicture streams.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain
  • Player6.CurrentSubpictureStream
  • Player6.EC_DVD_SUBPICTURE_STREAM_CHANGE
  • Player6.GetSubpictureLanguage
  • Player6.SubpictureOn


Player6.TitlesAvailable

This property retrieves the number of titles available in the current volume.

Syntax

MediaPlayer.DVD.TitlesAvailable

Possible Values

This property is a read-only ULONG.


Player6.TotalTitleTime

This property retrieves the total playback time for the current title.

Syntax

MediaPlayer.DVD.TotalTitleTime

Possible Values

This property is a read-only BSTR.

Remarks

This property resolves to a string indicating the total playback time for the current title in the form of "hh:mm:ss:ff" (hours, minutes, seconds, and frames, each two digits). The number of frames per second for the DVD title is either 25 or 30 and is defined by the read-only FramesPerSecond property.

By design, this property is restricted to simple linear movies.

The current domain must be TT_DOM when you retrieve this property.

See Also

  • Player6.CurrentDomain


Player6.TransparentAtStart

This property specifies or retrieves a value indicating whether the Windows Media Player control is transparent before play begins and after play ends.

Syntax

MediaPlayer.TransparentAtStart

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The control is transparent.
false | Default. The control is not transparent.

Remarks

If you set this property to true in Microsoft Visual Basic®, you should set the ClipControls property on the parent object to false. Otherwise, the background does not repaint.

See Also

  • Customizing the User Interface


Player6.UniqueID

This property retrieves the unique identifier associated with the DVD volume.

Syntax

MediaPlayer.DVD.UniqueID

Possible Values

This property is a read-only BSTR.

Remarks

The unique identifier is specific to an individual side of a specific DVD disc.

The current domain must be STOP_DOM when you get this property.

See Also

  • Player6.CurrentDomain


Player6.VideoBorder3D

This property specifies or retrieves a value indicating whether the three-dimensional video border effect is enabled.

Syntax

MediaPlayer.VideoBorder3D

Possible Values

This property is a read/write Boolean containing one of the following values.

Value | Description
true | The 3-D border is enabled.
false | Default. The 3-D border is disabled.

Remarks

The 3-D video border is 1 pixel wide. It is drawn around the video display panel and the video border, if one is present.

See Also

  • Customizing the User Interface
  • Player6.VideoBorderColor
  • Player6.VideoBorderWidth


Player6.VideoBorderColor

This property specifies or retrieves the color of the video border.

Syntax

MediaPlayer.VideoBorderColor

Possible Values

This property is a read/write OLE_COLOR value. The default video border color is black.

Remarks

The Windows Media Player control draws a video border around the video display panel in the color specified by this property and with a width specified by the VideoBorderWidth property.

See Also

  • Customizing the User Interface
  • Player6.VideoBorder3D
  • Player6.VideoBorderWidth


Player6.VideoBorderWidth

This property specifies or retrieves the width of the video border, in pixels.

Syntax

MediaPlayer.VideoBorderWidth

Possible Values

This property is a read/write Long with a default value of zero.

Remarks

The Windows Media Player control draws a video border around the video display panel with a width specified by this property and in the color specified by the VideoBorderColor property.

The default value of zero indicates that Windows Media Player does not display any video border.

See Also

  • Customizing the User Interface
  • Player6.VideoBorder3D
  • Player6.VideoBorderColor


Player6.Volume

This property specifies or retrieves the volume, in hundredths of decibels.

Syntax

MediaPlayer.Volume

Possible Values

This property is a read/write Long ranging from –10,000 to zero. It has a default value of –600.

Remarks

Zero specifies full volume and –10,000 specifies no volume.

Not all devices support 10,000 discrete steps of volume.

If no value is specified for this property, it defaults to the last volume setting established for the Windows Media Player control.

See Also

  • Playback Methods and Properties
  • Player6.Balance


Player6.VolumesAvailable

This property retrieves the number of volumes in the volume set.

Syntax

MediaPlayer.DVD.VolumesAvailable

Possible Values

This property is a read-only ULONG.


Windows Media Player Control Version 6.4 Methods

The Windows Media Player control version 6.4 supports the following methods.

Method | Description
AboutBox | Displays version and copyright information about the Windows Media Player control.
BackwardScan | Searches backward through the current disc at the specified speed.
ButtonActivate | Activates the selected button.
ButtonSelectAndActivate | Selects and activates the specified button.
Cancel | Cancels the Open method before the file completes opening.
ChapterPlay | Plays the media file with the specified title index and chapter value.
ChapterPlayAutoStop | Instructs the DVD player to start playing at the specified chapter within the specified title and to play the number of chapters specified.
ChapterSearch | Halts playback of the current chapter and starts playback from the specified chapter within the same title.
FastForward | Scans rapidly forward through the current clip.
FastReverse | Scans rapidly backward through the current clip.
ForwardScan | Searches forward through the current disc at the specified speed.
GetAllGPRMs | Retrieves the current contents of all general parameter registers (GPRMs).
GetAllSPRMs | Retrieves the current contents of all system parameter registers (SPRMs).
GetAudioLanguage | Retrieves a value indicating the language of the specified audio stream within the current title.
GetCodecDescription | Retrieves the descriptive name of the given codec.
GetCodecInstalled | Retrieves a value indicating whether a given codec is installed.
GetCodecURL | Retrieves the URL location containing additional information about the given codec.
GetCurrentEntry | Retrieves the current clip being played by the Windows Media Player control.
GetMarkerName | Retrieves the name of a marker, given its marker number.
GetMarkerTime | Retrieves a value indicating the presentation time of a given marker.
GetMediaInfoString | Retrieves show or clip information.
GetMediaParameter | Retrieves the value of the specified parameter for an indexed Windows Media metafile entry.
GetMediaParameterName | Retrieves the name of the specified parameter for an indexed Windows Media metafile entry.
GetMoreInfoURL | Retrieves a URL to additional information about the presentation.
GetNumberOfChapters | Retrieves the number of chapters defined for the specified title.
GetStreamGroup | Retrieves the group associated with the given media stream.
GetStreamName | Retrieves the name of the given stream.
GetStreamSelected | Retrieves a value indicating whether the given stream is currently selected.
GetSubpictureLanguage | Retrieves a value indicating the language for the specified subpicture stream.
GoUp | Halts playback of the current media file and starts playback of the designated previous program chain (PGC).
IsSoundCardEnabled | Retrieves a value indicating whether the computer's sound card is enabled.
LeftButtonSelect | Selects the left directional button from the displayed menu.
LowerButtonSelect | Selects the lower directional button from the displayed menu.
MenuCall | Displays the specified menu on the screen.
Next | Jumps to the next clip in a playlist.
NextPGSearch | Halts playback of the current program and starts playback from the next program within the program chain (PGC).
Open | Asynchronously opens a specified clip.
Pause | Suspends playback at the current position in the clip.
Play | Starts playing a clip from the starting position or continues playing a paused or stopped clip.
Previous | Jumps to the previous clip in a playlist.
PrevPGSearch | Halts playback of the current program and starts playback from the previous program within the program chain (PGC).
ResumeFromMenu | Returns to playing a title from a menu.
RightButtonSelect | Selects the right directional button from the displayed menu.
SetCurrentEntry | Selects a clip for playback by Windows Media Player.
ShowDialog | Displays a modal dialog box containing a specified Windows Media Player dialog.
StillOff | Resumes playback, canceling still mode.
Stop | Stops playback of the current clip.
StreamSelect | Selects the media stream indicated by the specified stream number.
TimePlay | Plays the media file with the specified title index, starting at the specified time.
TimeSearch | Halts playback of the current chapter and starts playback from the specified time in the same media file.
TitlePlay | Finds the media file with the specified title index and plays it back.
TopPGSearch | Halts playback of the current program and restarts playback of the current program within the program chain (PGC).
UOPValid | Retrieves a value indicating whether the specified user operation is currently valid.
UpperButtonSelect | Selects the upper directional button from the displayed menu.


Player6.AboutBox

This method displays version and copyright information about the Windows Media Player control.

Syntax

MediaPlayer.AboutBox()

Return Value

This method does not return a value.


Player6.BackwardScan

This method searches backward through the current disc at the specified speed.

Syntax

MediaPlayer.DVD.BackwardScan(dblSpeed)

Parameters

dblSpeed

Double value indicating the speed at which to search through the media file. This value is a multiplier, where 1.0 is the authored speed. A value of 2.5 will search backward at two and one-half times the authored speed, while a value of 0.5 will search backward at half the authored speed. Note that the actual speed of playback depends on the capabilities of the video decoder, and may differ from the specified rate.

Return Value

This method does not return a value.


Player6.ButtonActivate

This method activates the selected button.

Syntax

MediaPlayer.DVD.ButtonActivate()

Return Value

This method does not return a value.

Remarks

Selecting a DVD button simply highlights the button but does not activate it. Selecting is the programmatic equivalent of tabbing to a button but not pressing the space bar or ENTER key. Activating is the programmatic equivalent of tabbing to a button and then pressing the space bar or ENTER key.


Player6.ButtonSelectAndActivate

This method selects and activates the specified button.

Syntax

MediaPlayer.DVD.ButtonSelectAndActivate(dblButton)

Parameters

dblButton

ULONG value ranging from 1 to 36 indicating the button that will be selected and activated.

Return Value

This method does not return a value.

Remarks

Typically, electronic remote control devices have buttons that activate the various functions of a digital video disc (DVD) playback unit. Call this method when a user clicks a button on the control device.

Users can activate on-screen DVD-Video menu buttons by clicking the mouse. In addition, on-screen DVD-Video menu buttons can be selected and activated through script. Users will receive whatever feedback was authored on the DVD-Video disc for selection and activation of the button.

See Also

  • Player6.EC_DVD_BUTTON_CHANGE


Player6.Cancel

This method cancels the asynchronous Open method before a clip is completely opened.

Syntax

MediaPlayer.Cancel()

Return Value

This method does not return a value.

Remarks

This method does not close a connection to a computer running Microsoft® NetShow™ Theater Server. To close a NetShow Theater Server connection, set the FileName property to an empty string.


Player6.ChapterPlay

This method plays the media file with the specified title index and chapter value.

Syntax

MediaPlayer.DVD.ChapterPlay(uTitle, uChapter)

Parameters

uTitle

ULONG value between 1 and 99 indicating the title number that the Windows Media Player control will play.

uChapter

ULONG value between 1 and 999 indicating the chapter within the specified title where the Windows Media Player control will start playback.

Return Value

This method does not return a value.


Player6.ChapterPlayAutoStop

This method instructs the digital video disc (DVD) player to start playing at the specified chapter within the specified title and to play the number of chapters specified.

Syntax

MediaPlayer.DVD.ChapterPlayAutoStop(uTitle, uChapter, uChaptersToPlay)

Parameters

uTitle

ULONG value between 1 and 99 indicating the title number that the Windows Media Player control will play.

uChapter

ULONG value between 1 and 999 indicating the chapter within the specified title where the Windows Media Player control will start playback.

uChaptersToPlay

ULONG value indicating the number of chapters to play, beginning with the start chapter.

Return Value

This method does not return a value.

See Also

  • Player6.EC_DVD_CHAPTER_AUTOSTOP


Player6.ChapterSearch

This method halts playback of the current chapter and starts playback from the specified chapter within the same title.

Syntax

MediaPlayer.DVD.ChapterSearch(uChapter)

Parameters

uChapter

ULONG value between 1 and 999 indicating the chapter where playback will begin.

Return Value

This method does not return a value.


Player6.FastForward

This method scans rapidly forward through the current presentation.

Syntax

MediaPlayer.FastForward()

Return Value

This method does not return a value.

Remarks

This method performs the same action as the user holding down the fast-forward button on the control bar. You can also fast-forward through a clip by setting the Rate property to a higher value and playing the clip.

See Also

  • Playback Methods and Properties
  • Player6.FastReverse
  • Player6.Pause
  • Player6.Play
  • Player6.Rate
  • Player6.Stop


Player6.FastReverse

This method scans rapidly backward through the current presentation.

Syntax

MediaPlayer.FastReverse()

Return Value

This method does not return a value.

Remarks

This method performs the same action as the user holding down the fast-reverse button on the control bar. You can also fast-reverse by stopping the clip, setting the Rate property to a negative value, and restarting the clip.

See Also

  • Playback Methods and Properties
  • Player6.FastForward
  • Player6.Pause
  • Player6.Play
  • Player6.Rate
  • Player6.Stop


Player6.ForwardScan

This method searches forward through the current disc at the specified speed.

Syntax

MediaPlayer.DVD.ForwardScan(uSpeed)

Parameters

uSpeed

Double value indicating how quickly the Windows Media Player control will search through the media file. This value is a multiplier, where 1.0 is the authored speed. A value of 2.5 will search forward at two and one-half times the authored speed, while a value of 0.5 will search forward at half the authored speed. Note that the actual speed of playback depends on the capabilities of the video decoder, and may differ from the specified rate.

Return Value

This method does not return a value.


Player6.GetAllGPRMs

This method retrieves an array of the values in the general parameter registers.

Syntax

MediaPlayer.DVD.GetAllGPRMs()

Return Value

Returns an array of the values in the general parameter registers (GPRMARRAY).

Remarks

GPRMs are general parameter registers. This method is for advanced users and requires specific knowledge of the digital video disc (DVD) specifications. Use of GPRMs is title specific. See the DVD specifications for an explanation of GPRMs. The returned array contains 16 16-bit variables representing the values of the registers.


Player6.GetAllSPRMs

This method retrieves an array of the values in the system parameter registers.

Syntax

MediaPlayer.DVD.GetAllSPRMs()

Return Value

Returns an array of the values in the system parameter registers (SPRMARRAY).

Remarks

SPRMs are system parameter registers. This method is for advanced users and requires specific knowledge of the digital video disc (DVD) specifications. See the DVD specification for use of individual registers. The returned array contains 24 16-bit variables representing the values of the registers.


Player6.GetAudioLanguage

This method retrieves a value indicating the language of the specified audio stream within the current title.

Syntax

MediaPlayer.DVD.GetAudioLanguage(uStream)

Parameters

uStream

ULONG value indicating the audio stream number.

Return Value

Returns a BSTR containing one of the following values identifying a language according to the Alpha-2 Code defined in ISO-639.

Value | Language
aa | Afar
ab | Abkhazian
af | Afrikaans
am | Amharic
ar | Arabic
as | Assamese
ay | Aymara
az | Azerbaijani
ba | Bashkir
be | Byelorussian
bg | Bulgarian
bh | Bihari
bi | Bislama
bn | Bengali; Bangla
bo | Tibetan
br | Breton
ca | Catalan
co | Corsican
cs | Czech
cy | Welsh
da | Danish
de | German
dz | Bhutani
el | Greek
en | English
eo | Esperanto
es | Spanish
et | Estonian
eu | Basque
fa | Persian
fi | Finnish
fj | Fijian
fo | Faroese
fr | French
fy | Frisian
ga | Irish
gd | Scots Gaelic
gl | Galician
gn | Guarani
gu | Gujarati
ha | Hausa
he | Hebrew
hi | Hindi
hr | Croatian
hu | Hungarian
hy | Armenian
ia | Interlingua
id | Indonesian
ie | Interlingue
ik | Inupiak
is | Icelandic
it | Italian
iu | Inuktitut
ja | Japanese
jw | Javanese
ka | Georgian
kk | Kazakh
kl | Greenlandic
km | Cambodian
kn | Kannada
ko | Korean
ky | Kirghiz
la | Latin
ln | Lingala
lo | Laothian
lt | Lithuanian
lv | Latvian, Lettish
mg | Malagasy
mi | Maori
mk | Macedonian (FYROM)
ml | Malayalam
mn | Mongolian
mo | Moldavian
mr | Marathi
ms | Malay
mt | Maltese
my | Burmese
na | Nauru
ne | Nepali
nl | Dutch
no | Norwegian
oc | Occitan
om | (Afan) Oromo
or | Oriya
pa | Punjabi
pl | Polish
ps | Pashto, Pushto
pt | Portuguese
qu | Quechua
rm | Rhaeto-Romance
rn | Kirundi
ro | Romanian
ru | Russian
rw | Kinyarwanda
sa | Sanskrit
sd | Sindhi
sg | Sangho
sh | Serbo-Croatian
si | Sinhalese
sk | Slovak
sl | Slovenian
sm | Samoan
sn | Shona
so | Somali
sq | Albanian
sr | Serbian
ss | Siswati
st | Sesotho
su | Sundanese
sv | Swedish
sw | Swahili
ta | Tamil
te | Telugu
tg | Tajik
th | Thai
ti | Tigrinya
tk | Turkmen
tl | Tagalog
tn | Setswana
to | Tonga
tr | Turkish
ts | Tsonga
tt | Tatar
tw | Twi
ug | Uighur
uk | Ukrainian
ur | Urdu
uz | Uzbek
vi | Vietnamese
vo | Volapuk
wo | Wolof
xh | Xhosa
yi | Yiddish
yo | Yoruba
za | Zhuang
zh | Chinese
zu | Zulu


Player6.GetCodecDescription

This method retrieves the descriptive name of the given codec.

Syntax

MediaPlayer.GetCodecDescription(sCodecNum)

Parameters

sCodecNum

Long value indicating the codec number.

Return Value

Returns a String containing the descriptive name of the given codec. This method returns a null string if the codec specified by the sCodecNum parameter is not found.

Remarks

The codec numbers start with 1. You will get an error if you use zero. Typically, the codec number is 1 for audio and 2 for video. Valid values for codec numbers range from 1 to the value of the CodecCount property.

See Also

  • Player6.CodecCount
  • Player6.GetCodecInstalled
  • Player6.GetCodecURL


Player6.GetCodecInstalled

This method retrieves a value indicating whether a given codec is installed.

Syntax

MediaPlayer.GetCodecInstalled(lCodecNum)

Parameters

lCodecNum

Long value indicating the codec number.

Return Value

Returns a Boolean containing one of the following values.

Value | Description
true | The specified codec is installed.
false | The specified codec is not installed.

Remarks

Codec numbers start with 1. You will get an error if you use zero. Typically, the codec number is 1 for audio and 2 for video. Valid values for codec numbers range from 1 to the value of the CodecCount property.

See Also

  • Player6.CodecCount
  • Player6.GetCodecDescription
  • Player6.GetCodecURL


Player6.GetCodecURL

This method retrieves the URL location containing additional information about the given codec.

Syntax

MediaPlayer.GetCodecURL(lCodecNum)

Parameters

lCodecNum

Long value indicating the codec number.

Return Value

Returns a String value indicating the URL location that contains additional information about the given codec. This method returns a null string if the specified codec is not found.

Remarks

Codec numbers start with 1. You will get an error if you use zero. Typically, the codec number is 1 for audio and 2 for video. Valid values for codec numbers range from 1 to the value of the CodecCount property.

See Also

  • Player6.CodecCount
  • Player6.GetCodecDescription
  • Player6.GetCodecInstalled


Player6.GetCurrentEntry

This method retrieves the current clip being played by the Windows Media Player control.

Syntax

MediaPlayer.GetCurrentEntry()

Return Value

Long value indicating the index number of the current ENTRY element being played, based on its order in the specified Windows Media metafile. If Windows Media Player is not currently playing a file, this function will return zero.

Remarks

The first ENTRY element in a Windows Media metafile has an index number of 1. This method retrieves the index number of the current entry. To select an entry, call the SetCurrentEntry method.

Note This scripting method is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.

See Also

  • Player6.EntryCount
  • Player6.GetMediaParameter
  • Player6.GetMediaParameterName
  • Player6.SetCurrentEntry


Player6.GetMarkerName

This method retrieves the name of a marker, given its marker number.

Syntax

MediaPlayer.GetMarkerName(lMarkerNum)

Parameters

lMarkerNum

Long value indicating the number of the marker name to return.

Return Value

Returns a String containing the name of the marker. This method returns a null string if the specified marker does not exist.

Remarks

Some media clips do not contain markers. Retrieve the MarkerCount property to find out how many markers are in the current clip. Marker numbers start at 1. If a clip has no markers, the value of MarkerCount is zero. The following example tests MarkerCount before displaying a message box with the marker name:

If MediaPlayer1.MarkerCount > 0 Then
  MsgBox "Marker 1 is named " + MediaPlayer.GetMarkerName(1) + "."
End If

See Also

  • Playback Methods and Properties
  • Player6.CurrentMarker
  • Player6.GetMarkerTime
  • Player6.MarkerCount


Player6.GetMarkerTime

This method retrieves a value indicating the presentation time of a given marker.

Syntax

MediaPlayer.GetMarkerTime(lMarkerNum)

Parameters

lMarkerNum

Long value indicating the number of the marker to return.

Return Value

Returns a Double value indicating the presentation time of a given marker. This method returns a null string if the specified marker does not exist.

Remarks

Some media clips do not contain markers. Use the MarkerCount property to find out how many markers are in the current clip. Marker numbers start at 1. If a clip has no markers, the value of MarkerCount is zero. The following example tests MarkerCount before displaying a message box with the marker time:

If (MediaPlayer1.MarkerCount > 0) Then
  MsgBox "Marker 1 is at" + Str$(MediaPlayer1.GetMarkerTime(1)) _
     + " seconds."
End If

See Also

  • Playback Methods and Properties
  • Player6.CurrentMarker
  • Player6.GetMarkerName
  • Player6.MarkerCount


Player6.GetMediaInfoString

This method retrieves show or clip information.

Syntax

MediaPlayer.GetMediaInfoString(lMediaInfoType)

Parameters

lMediaInfoType

Long value indicating the type of show or clip information to return. It can have one of the following possible values.

Value | Visual Basic constant | Description
0 | mpShowFilename | The name of the Windows Media metafile containing the playlist.
1 | mpShowTitle | The playlist's title.
2 | mpShowAuthor | The playlist's author.
3 | mpShowCopyright | Copyright information for the playlist.
4 | mpShowRating | No longer supported.
5 | mpShowDescription | No longer supported.
6 | mpShowLogoIcon | The URL for the playlist's logo icon.
7 | mpClipFilename | No longer supported.
8 | mpClipTitle | The clip's title.
9 | mpClipAuthor | The clip's author.
10 | mpClipCopyright | Copyright information for the clip.
11 | mpClipRating | Rating information for the clip.
12 | mpClipDescription | A description of the clip.
13 | mpClipLogoIcon | The URL for the clip's logo icon.
14 | mpBannerImage | The banner image URL.
15 | mpBannerMoreInfo | The more-info URL associated with the banner.
16 | mpWatermark | The watermark image URL.

Return Value

Returns a String value associated with the given media information type.

Remarks

Show information refers to a Windows Media metafile containing a playlist.

Clip information refers to one of the individual media file entries specified in the playlist. Clip information comes either from the media file or from the Windows Media metafile referencing the media file. This method returns clip information from the Windows Media metafile if it is available. If the clip is accessed directly, this method returns information from the media file.

See Also

  • Retrieving Presentation Information


Player6.GetMediaParameter

This method retrieves the value of the specified parameter for an indexed Windows Media metafile entry.

Syntax

MediaPlayer.GetMediaParameter(lEntryNum, sName)

Parameters

lEntryNum

Long value indicating the index number of an ENTRY element in the Windows Media metafile.

sName

BSTR value indicating the NAME attribute of a PARAM element within the specified ENTRY element. This value is not case sensitive.

Return Value

Returns a String value representing the VALUE attribute of the specified PARAM element. This method returns a null value if lEntryNum is outside the range of the EntryCount property, or if no PARAM element within the specified ENTRY element has a NAME attribute equal to sName.

Remarks

The PARAM element allows you to place additional information into a Windows Media metafile, which the Windows Media Player control can then access through scripting. For example, you could insert the names of the producers of all the media files inside the Windows Media metafile and display them in HTML somewhere near the Windows Media Player window.

Use this method to determine the values of the PARAM elements within a Windows Media metafile ENTRY element. Call the GetMediaParameterName method to determine names associated with PARAM elements.

The first ENTRY element in a Windows Media metafile has a lEntryNum index number of 1. Index number 0 is reserved for child elements of the metafile tag, which applies to information valid for the entire show.

An example Windows Media metafile might look like the following.

<ASX VERSION="3.0">
  <TITLE>The Title of the Show<TITLE>
  <ENTRY>
    <REF HREF="YourMediaFilename.asf" />
    <TITLE>The Title of the Track</TITLE>
    <PARAM NAME="Producer" VALUE="Jane D.">
  </ENTRY>
</ASX>

To retrieve the producer information for the first entry, call the method as follows.

MediaPlayer.GetMediaParameter( 1, "Producer");

This method call would return the string "Jane D.".

Note This scripting method is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.

See Also

  • Player6.EntryCount
  • Player6.GetMediaParameterName


Player6.GetMediaParameterName

This method retrieves the name of the specified parameter for an indexed Windows Media metafile entry.

Syntax

MediaPlayer.GetMediaParameterName(lEntryNum, lParamNum)

Parameters

lEntryNum

Long value indicating the index number of an ENTRY element in the Windows Media metafile.

lParamNum

Long value indicating the index number of a PARAM element within the specified ENTRY element.

Return Value

Returns a String value representing the NAME attribute of the specified PARAM element. This method returns a null value if lEntryNum is outside the range of the EntryCount property, or if no PARAM element numbered lParamNum exists within the specified ENTRY element.

Remarks

The PARAM element allows you to place additional information into a Windows Media metafile, which the Windows Media Player control can then access through scripting. For example, you could insert the names of the producers of the media files inside the Windows Media metafile and display them in HTML somewhere near the Windows Media Player window.

Use this method to determine the names of the PARAM elements within a Windows Media metafile ENTRY element. You can then call the GetMediaParameter method to determine the value associated with each name.

The first ENTRY element in a Windows Media metafile has a lEntryNum index number of 1. Index number 0 is reserved for child elements of the Windows Media metafile tag, which applies to information valid for the entire show.

An example Windows Media metafile might look like the following.

<ASX VERSION="3.0">
    <TITLE>The Title of the Show<TITLE>
<ENTRY>
    <REF HREF="YourMediaFilename.asf" />
    <TITLE>The Title of the Track</TITLE>
    <PARAM NAME="Producer" VALUE="Jane D.">
</ENTRY>
</ASX>

To retrieve the name of the first PARAM element, call the method as follows.

MediaPlayer.GetMediaParameterName( 1, 1 );

This method call would return the string "Producer".

Note This scripting method is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.

See Also

  • Player6.EntryCount
  • Player6.GetMediaParameter


Player6.GetMoreInfoURL

This method retrieves a URL to additional information about the presentation.

Syntax

MediaPlayer.GetMoreInfoURL(lMoreInfoType)

Parameters

lMoreInfoType

Long value indicating the type of information contained at the URL location. It can have one of the following possible values.

Value | Visual Basic constant | Description
0 | mpShowURL | More-information URL for the show.
1 | mpClipURL | More-information URL for the clip.
2 | mpBannerURL | More-information URL for the banner.

Return Value

Returns a String value indicating a URL to additional information about the presentation.

Remarks

This information is contained in the Windows Media metafile describing the current playlist.


Player6.GetNumberOfChapters

This method retrieves the number of chapters defined for the specified title.

Syntax

MediaPlayer.DVD.GetNumberOfChapters(uTitle)

Parameters

uTitle

ULONG value indicating the title.

Return Value

Returns a ULONG value indicating the number of chapters defined for the title.


Player6.GetStreamGroup

This method retrieves the group associated with the given media stream.

Syntax

MediaPlayer.GetStreamGroup(lStreamNum)

Parameters

lStreamNum

Long value indicating a stream number.

Return Value

Returns a Long value indicating the group associated with the given media stream.

Remarks

Stream numbers are zero-based. Valid values for stream numbers range from zero to the value of the StreamCount property minus one.

Related streams are often grouped together. For example, a stream group could be made up of audio language tracks. Only one stream in a group can be selected at any one time. Selecting a stream in a group automatically deselects all other streams in that group.

See Also

  • Player6.GetStreamName
  • Player6.GetStreamSelected
  • Player6.StreamCount
  • Player6.StreamSelect


Player6.GetStreamName

This method retrieves the name of the given stream.

Syntax

MediaPlayer.GetStreamName(lStreamNum)

Parameters

lStreamNum

Long value indicating a stream ID number.

Return Value

Returns a String value representing the name of the stream specified by lStreamNum.

Remarks

Stream numbers are zero-based. Valid values for stream numbers range from zero to the value of the StreamCount property minus one.

See Also

  • Player6.GetStreamSelected
  • Player6.StreamCount
  • Player6.StreamSelect


Player6.GetStreamSelected

This method retrieves a value indicating whether the specified stream is currently selected.

Syntax

MediaPlayer.GetStreamSelected(lStreamNum)

Parameters

lStreamNum

Long value indicating a stream ID number.

Return Value

Returns a Boolean containing one of the following values.

Value | Description
true | The specified stream is currently selected.
false | The specified stream is not currently selected.

Remarks

Stream numbers are zero-based. Valid values for stream numbers range from zero to the value of the StreamCount property minus one.

See Also

  • Player6.GetStreamName
  • Player6.StreamCount
  • Player6.StreamSelect


Player6.GetSubpictureLanguage

This method retrieves a value indicating the language for the specified subpicture stream.

Syntax

MediaPlayer.DVD.GetSubpictureLanguage(uStream)

Parameters

uStream

ULONG value indicating the subpicture stream number.

Return Value

Returns a BSTR value identifying a language according to the Alpha-2 Code defined in ISO-639. See GetAudioLanguage for a table of possible values.

Remarks

Subpictures are encoded graphics, such as subtitles or menus, that can be displayed over the top of the video.

This method returns an error unless the domain is TT_DOM. For more information on domains, see the CurrentDomain property.

See Also

  • Player6.CurrentSubpictureStream
  • Player6.EC_DVD_SUBPICTURE_STREAM_CHANGE
  • Player6.SubpictureOn
  • Player6.SubpictureStreamsAvailable


Player6.GoUp

This method halts playback of the current media file and starts playback of the designated previous program chain (PGC).

Syntax

MediaPlayer.DVD.GoUp()

Return Value

This method does not return a value.

Remarks

Each PGC is associated with a previous PGC at authoring time. This method sets the previous PGC as the new playback file.


Player6.IsSoundCardEnabled

This method retrieves a value indicating whether the computer's sound card is enabled.

Syntax

MediaPlayer.IsSoundCardEnabled()

Return Value

Returns a Boolean containing one of the following values.

Value | Description
true | The computer's sound card is enabled.
false | The computer's sound card is disabled.


Player6.LeftButtonSelect

This method selects the left directional button from the displayed menu.

Syntax

MediaPlayer.DVD.LeftButtonSelect()

Return Value

This method does not return a value.

Remarks

Physical or electronic remote control devices often have a group of four directional buttons, used for certain types of operations such as menu navigation. Call this method when a user clicks the left directional button on the control device.

Selecting a DVD button simply highlights the button but does not activate the button. Selecting is the programmatic equivalent of tabbing to a button but not pressing the space bar or ENTER key. Activating is the programmatic equivalent of tabbing to a button and then pressing the space bar or ENTER key.


Player6.LowerButtonSelect

This method selects the lower directional button from the displayed menu.

Syntax

MediaPlayer.DVD.LowerButtonSelect()

Return Value

This method does not return a value.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). Call this method when a user clicks the lower directional button on the control device.

Selecting a DVD button simply highlights the button but does not activate the button. Selecting is the programmatic equivalent of tabbing to a button but not pressing the space bar or ENTER key. Activating is the programmatic equivalent of tabbing to a button and then pressing the space bar or ENTER key.


Player6.MenuCall

This method displays the specified menu on the screen.

Syntax

MediaPlayer.DVD.MenuCall(uMenuID)

Parameters

uMenuID

ULONG value indicating the menu to display. It can have one of the following possible values.

Value | Description
2 | Title Menu
3 | Root Menu
4 | Sub-picture Menu
5 | Audio Menu
6 | Angle Menu
7 | Chapter Menu

Return Value

This method does not return a value.


Player6.Next

This method jumps to the next clip in the playlist.

Syntax

MediaPlayer.Next()

Return Value

This method does not return a value.

See Also

  • Player6.Previous
  • Using Playlists


Player6.NextPGSearch

This method halts playback of the current program and starts playback from the next program within the program chain (PGC).

Syntax

MediaPlayer.DVD.NextPGSearch()

Return Value

This method does not return a value.

Remarks

A program is usually equivalent to a chapter, and a PGC is usually equivalent to a title. In the case of One_Sequential_PGC_Titles, each program is required to be a chapter and each title has only one PGC, but in other cases (especially with random/shuffle PGCs and parental blocks) there can be more than one program between chapters and there can be more than one PGC in a title.


Player6.Open

This method asynchronously opens the clip with the specified name.

Syntax

MediaPlayer.Open(sTitleName)

Parameters

sTitleName

String value representing the name of the clip to open, including its protocol, path, or HTTP URL.

Return Value

This method does not return a value.

Remarks

This method performs the same function as setting the FileName property, but it works asynchronously, allowing the calling application to continue performing tasks while the clip is being opened. Use the Cancel method to abort the Open method before the file is completely loaded.

See Also

  • Playback Methods and Properties
  • Player6.Cancel
  • Player6.FileName


Player6.Pause

This method suspends playback at the current position in the clip.

Syntax

MediaPlayer.Pause()

Return Value

This method does not return a value.

Remarks

This method performs the same action as clicking the pause button on the control bar.

If the value of the SendPlayStateChangeEvents property is true and the file is playing, calling this method causes a PlayStateChange event to occur.

When a file is paused, the client control does not give up any system resources, such as the audio device.

See Also

  • Playback Methods and Properties
  • Player6.FastForward
  • Player6.FastReverse
  • Player6.Play
  • Player6.Stop


Player6.Play

This method starts playing a clip from the starting position or continues playing a paused clip.

Syntax

MediaPlayer.Play()

Return Value

This method does not return a value.

Remarks

If the value of the SendPlayStateChangeEvents property is true and the file is not already playing, calling this method causes a PlayStateChange event to occur.

See Also

  • Playback Methods and Properties
  • Player6.FastForward
  • Player6.FastReverse
  • Player6.Pause
  • Player6.Stop


Player6.Previous

This method jumps to the previous clip in the playlist.

Syntax

MediaPlayer.Previous()

Return Value

This method does not return a value.

See Also

  • Player6.Next
  • Using Playlists


Player6.PrevPGSearch

This method halts playback of the current program and starts playback from the previous program within the program chain (PGC).

Syntax

MediaPlayer.DVD.PrevPGSearch()

Return Value

This method does not return a value.

Remarks

A program is usually equivalent to a chapter, and a PGC is usually equivalent to a title. In the case of One_Sequential_PGC_Titles, each program is required to be a chapter and each title has only one PGC, but in other cases (especially with random/shuffle PGCs and parental blocks) there can be more than one program between chapters and there can be more than one PGC in a title.


Player6.ResumeFromMenu

This method returns to playing back a title from a menu.

Syntax

MediaPlayer.DVD.ResumeFromMenu()

Return Value

This method does not return a value.

Remarks

If the file is stopped or already running, this method does nothing.

This method returns to title playback in the TT_DOM domain. Applications typically call this method after calling MenuCall, which puts the digital video disc (DVD) player in either the VTSM_DOM domain or the VMGM_DOM domain.

For more information on domains, see the CurrentDomain property.


Player6.RightButtonSelect

This method selects the right directional button from the displayed menu.

Syntax

MediaPlayer.DVD.RightButtonSelect()

Return Value

This method does not return a value.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). Call this method when a user clicks the right directional button on the control device.

Selecting a DVD button simply highlights the button but does not activate the button. Selecting is the programmatic equivalent of tabbing to a button but not pressing the space bar or ENTER key. Activating is the programmatic equivalent of tabbing to a button and then pressing the space bar or ENTER key.


Player6.SetCurrentEntry

This method selects a clip for playback by Windows Media Player.

Syntax

MediaPlayer.SetCurrentEntry(lWhichEntry)

Parameters

lWhichEntry

Long value indicating the index number of the ENTRY element that defines the media file to play back.

Return Value

This method does not return a value.

Remarks

If the value for lWhichEntry is valid for the specified Windows Media metafile, Windows Media Player will begin playing the clip immediately. If the value is invalid, Windows Media Player will perform no action.

The first ENTRY element in a Windows Media metafile has an index number of 1. Setting the current entry value to zero or to a number greater than the value of the EntryCount property will result in an error.

Note This scripting method is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.

See Also

  • Player6.EntryCount
  • Player6.GetCurrentEntry
  • Player6.GetMediaParameter
  • Player6.GetMediaParameterName


Player6.ShowDialog

This method displays a modal dialog box containing a specified Windows Media Player dialog.

Syntax

MediaPlayer.ShowDialog(lDialogType)

Parameters

lDialogType

Long value indicating which dialog box to open. It can have one of the following possible values.

Value | Visual Basic constant | Description
0 | MpHelp | Opens the Help Topics dialog from the Help menu.
1 | MpStatistics | Opens the Statistics dialog from the View menu.
2 | MpOptions | Opens the Options dialog from the View menu.

Return Value

This method does not return a value.

Remarks

This method performs the same action as choosing items in the Windows Media Player application menu which open dialog boxes.

Note This scripting method is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft® Internet Explorer 5 includes a compatible version of Windows Media Player.


Player6.StillOff

This method resumes playback, canceling still mode.

Syntax

MediaPlayer.DVD.StillOff()

Return Value

This method does not return a value.

Remarks

If the display image was not in still mode, this method does nothing.


Player6.Stop

This method stops playback of the current clip.

Syntax

MediaPlayer.Stop()

Return Value

This method does not return a value.

Remarks

If the value of the SendPlayStateChangeEvents property is true and the file is not currently stopped, calling this method causes a PlayStateChange event to occur.

Calling this method does not change the current position unless the file is not seekable. Non-seekable files reset to the position specified by the SelectionStart property. This behavior is different than pressing the stop button on the Windows Media Player application, which always resets the current position to zero.

This method causes the Windows Media Player control to release any system resources it is using, such as the audio device.

To halt a play operation without changing the current position, use the Pause method.

See Also

  • Playback Methods and Properties
  • Player6.FastForward
  • Player6.FastReverse
  • Player6.Pause
  • Player6.Play


Player6.StreamSelect

This method selects the media stream indicated by the specified stream number.

Syntax

MediaPlayer.StreamSelect(lStreamNum)

Parameters

lStreamNum

Long value indicating a stream number to select.

Return Value

This method does not return a value.

Remarks

Stream numbers are zero-based. Valid values for stream numbers range from zero to the value of the StreamCount property minus one.

Related streams are often grouped together. For example, a stream group could be made up of audio language tracks. Only one stream in a group can be selected at any one time. Selecting a stream in a group automatically deselects all other streams in that group.

See Also

  • Player6.GetStreamName
  • Player6.GetStreamSelected
  • Player6.StreamCount


Player6.TimePlay

This method plays the media file with the specified title index, starting at the specified time.

Syntax

MediaPlayer.DVD.TimePlay(uTitle, sTime)

Parameters

uTitle

ULONG value indicating the title number Windows Media Player will play back. The value must be between 1 and 99.

sTime

String value defining the time to start playback in the form of "hh:mm:ss:ff" (hours, minutes, seconds, and frames, each two digits).

Return Value

This method does not return a value.

Remarks

Frames per second for the DVD title is either 25 or 30 and is defined by the read-only FramesPerSecond property.


Player6.TimeSearch

This method halts playback of the current chapter and starts playback from the specified time in the same media file.

Syntax

MediaPlayer.DVD.TimeSearch(sTime)

Parameters

sTime

String value defining the time to start playback in the form of "hh:mm:ss:ff" (hours, minutes, seconds, and frames, each two digits).

Return Value

This method does not return a value.

Remarks

Frames per second for the DVD title is either 25 or 30, and is defined by the read-only FramesPerSecond property.


Player6.TitlePlay

This method finds the media file with the specified title index and plays it back.

Syntax

MediaPlayer.DVD.TitlePlay(uTitle)

Parameters

uTitle

ULONG value between 1 and 99 indicating the title number the Windows Media Player control will play back.

Return Value

This method does not return a value.


Player6.TopPGSearch

This method halts playback of the current program and restarts playback of the current program within the program chain (PGC).

Syntax

MediaPlayer.DVD.TopPGSearch()

Return Value

This method does not return a value.

Remarks

A program is usually equivalent to a chapter, and a PGC is usually equivalent to a title. In the case of One_Sequential_PGC_Titles, each program is required to be a chapter and each title has only one PGC, but in other cases (especially with random/shuffle PGCs and parental blocks) there can be more than one program between chapters and there can be more than one PGC in a title.


Player6.UOPValid

This method retrieves a value that indicates whether the specified user operation is currently valid.

Syntax

MediaPlayer.DVD.UOPValid(uUOP)

Parameters

uUOP

ULONG value that specifies the user operation whose validity is being checked. It can have one of the following possible values.

Value | User Function
0 | TimePlay, TimeSearch
1 | ChapterPlay, ChapterSearch
2 | TitlePlay
3 | Stop
4 | GoUp in TT_DOM domain, GoUp in Menu-space domain
5 | TimeSearch, ChapterSearch
6 | PrevPGSearch, TopPGSearch
7 | NextPGSearch
8 | ForwardScan
9 | BackwardScan
10 | MenuCall with a parameter value of 2 (Title Menu)
11 | MenuCall with a parameter value of 3 (Root Menu)
12 | MenuCall with a parameter value of 4 (Sub-picture Menu)
13 | MenuCall with a parameter value of 5 (Audio Menu)
14 | MenuCall with a parameter value of 6 (Angle Menu)
15 | MenuCall with a parameter value of 7 (Chapter Menu)
16 | ResumeFromMenu
17 | UpperButtonSelect, LowerButtonSelect, LeftButtonSelect, RightButtonSelect, ButtonActivate, ButtonSelectAndActivate
18 | StillOff
19 | Pause
20 | EC_DVD_AUDIO_STREAM_CHANGE
21 | EC_DVD_SUBPICTURE_STREAM_CHANGE
22 | EC_DVD_ANGLE_CHANGE

Return Value

Returns a Boolean containing one of the following values.

Value | Description
true | The specified user operation is currently valid.
false | The specified user operation is currently invalid.


Player6.UpperButtonSelect

This method selects the upper directional button from the displayed menu.

Syntax

MediaPlayer.DVD.UpperButtonSelect()

Return Value

This method does not return a value.

Remarks

On physical or electronic remote control devices, there is often a group of four directional buttons used for certain types of operations (such as menu navigation). Call this method when a user clicks the upper directional button on the control device.

Selecting a DVD button simply highlights the button but does not activate the button. Selecting is the programmatic equivalent of tabbing to a button but not pressing the space bar or ENTER key. Activating is the programmatic equivalent of tabbing to a button and then pressing the space bar or ENTER key.


Windows Media Player Object Model Version 6.4 Events

The Windows Media Player Object Model version 6.4 supports the following events.

Event | Description
Buffering | Occurs when the Windows Media Player control begins or ends buffering.
Click | Occurs when a user clicks the mouse with the cursor on the Windows Media Player control.
DblClick | Occurs when a user double-clicks the mouse with the cursor on the Windows Media Player control.
Disconnect | Occurs when the Windows Media Player control is disconnected from the server.
DisplayModeChange | Occurs when the DisplayMode property changes.
DVDNotify | Occurs when a DVD-related notification is triggered.
EndOfStream | Occurs when the end of the clip is reached.
Error | Occurs when the Windows Media Player control has an error condition.
KeyDown | Occurs when a key is pressed.
KeyPress | Occurs when a key is pressed and released.
KeyUp | Occurs when a key is released.
MarkerHit | Occurs when a marker is reached.
MouseDown | Occurs when a mouse button is pressed.
MouseMove | Occurs when the mouse pointer is moved.
MouseUp | Occurs when a mouse button is released.
NewStream | Occurs when a new stream is started in a station.
OpenStateChange | Occurs when the Windows Media Player control changes its open state.
PlayStateChange | Occurs when the Windows Media Player control changes its play state.
PositionChange | Occurs when the current media position moves to a new position.
ReadyStateChange | Occurs when the Windows Media Player control's state of readiness changes.
ScriptCommand | Occurs when a synchronized command or URL is received.
Warning | Occurs when the Windows Media Player control encounters a possible problem.


Player6.Buffering

This event occurs when the Windows Media Player control begins or ends buffering.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="Buffering(bStart)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_Buffering(bStart)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

bStart

Boolean value specifying whether data buffering has started or finished. A value of true indicates that the data buffering has started.

Remarks

This event occurs when data begins or finishes buffering.

The properties of a Windows Media file (for example, how its images are stored) can initiate event buffering. Buffering also occurs whenever Windows Media file playback stops and then restarts (either from calls to the Stop and Play methods, or because the user pressed the stop and start buttons). However, other factors such as network congestion can cause data buffering to occur at almost any time while streamed content is being played.

The following example displays a message when data buffering occurs.

Sub MediaPlayer1_Buffering(Start)
  If Start = True Then      'Did buffering just begin?
    TextBox.Text = "Buffering..."
  Else   'Buffering done, clear text box
    TextBox.Text = ""
  End If
End Sub

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.BufferingCount


Player6.Click

This event occurs when a user clicks the mouse with the cursor in the image window.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="Click( iButton, iShiftState, fX, fY )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_Click( iButton, iShiftState, fX, fY )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iButton

Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

iShiftState

Integer value specifying a bit field with the least significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

fX

Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

fY

Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event occurs only if the value of the SendMouseClickEvents property is true.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.DblClick
  • Player6.MouseDown
  • Player6.MouseUp
  • Player6.SendMouseClickEvents


Player6.DblClick

This event occurs when a user double-clicks the mouse with the pointer in the image window.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="DblClick( iButton, iShiftState, fX, fY )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_DblClick( iButton, iShiftState, fX, fY )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iButton

Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

iShiftState

Integer value specifying a bit field with the least significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

fX

Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

fY

Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event occurs only if the value of the SendMouseClickEvents property is true.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.Click
  • Player6.MouseDown
  • Player6.MouseUp
  • Player6.SendMouseClickEvents


Player6.Disconnect

This event occurs when the Windows Media Player control is disconnected from the server.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="Disconnect(lResult)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_Disconnect(lResult)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lResult

Long value specifying the cause of the disconnection.

Remarks

This event is not supported in Netscape Navigator when the Windows Media Player control is embedded in a Web page.

A disconnection can be caused by a network problem, a problem with the server, or other factors.


Player6.DisplayModeChange

This event occurs when the DisplayMode property changes.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="DisplayModeChange()"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_DisplayModeChange()
    <!-- insert script commands -->
End Sub
</SCRIPT>

Remarks

The DisplayMode property specifies whether the current position is displayed in seconds or frames. The DisplayMode property and the DisplayModeChange event are valid only for local playback, not for streaming media.

See Also

  • Player6.DisplayMode


Player6.DVDNotify

This event occurs when a DVD-related notification is raised.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="DVDNotify( Event, Param1, Param2 )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_DVDNotify( Event, Param1, Param2 )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

Event

Value that specifies the DVD-specific event code that occurred. See DVD Event Codes.

Param1

Returned value specific to the current event code. Default value is zero.

Param2

Returned value specific to the current event code. Default value is zero.

See Also

  • DVD Event Codes
  • Using DVD Event Codes


Player6.EndOfStream

This event occurs when the end of the clip is reached.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="EndOfStream(lResult)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_EndOfStream(lResult)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lResult

Long value specifying the status of the clip after it has finished playing. A value of zero indicates the clip completed successfully.

See Also

  • Error Handling
  • Monitoring Stream Status and Network Reception
  • Player6.NewStream


Player6.Error

This event occurs when the Windows Media Player control has an error condition.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="Error( )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_Error( )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Remarks

Use this event to trap errors. This event occurs when the Windows Media Player control reports an error during playback. To process the error in your script, use the Microsoft Visual Basic® Err object or the Windows Media Player control ErrorCode, ErrorCorrection, and ErrorDescription properties.


Player6.KeyDown

This event occurs when the user presses a key.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="KeyDown(iKeyCode, iShiftState)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_KeyDown(iKeyCode, iShiftState)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iKeyCode

Integer value specifying a key code, such as vbKeyF1 (the F1 key) or vbKeyHome (the HOME key). To specify key codes, see the Microsoft® Visual Basic® documentation.

iShiftState

Integer value specifying a bit field with bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

Remarks

If the value of the SendKeyboardEvents property is true, this event occurs when the Windows Media Player control has focus and the user presses a key. If SendKeyboardEvents is false, this event does not occur.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.KeyPress
  • Player6.KeyUp
  • Player6.SendKeyboardEvents


Player6.KeyPress

This event occurs when the user presses and releases a key.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="KeyPress(iKeyAscii)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_KeyPress(iKeyAscii)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iKeyAscii

Integer value specifying a standard numeric ANSI keycode.

Remarks

If the value of the SendKeyboardEvents property is true, this event occurs when the Windows Media Player control has focus and the user presses and releases a key. If SendKeyboardEvents is false, this event does not occur.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.KeyDown
  • Player6.KeyUp
  • Player6.SendKeyboardEvents


Player6.KeyUp

This event occurs when the user releases a key.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="KeyUp(iKeyCode, iShiftState)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_KeyUp(iKeyCode, iShiftState)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iKeyCode

Integer value specifying a key code, such as vbKeyF1 (the F1 key) or vbKeyHome (the HOME key). To specify key codes, see the Microsoft Visual Basic documentation.

iShiftState

Integer value specifying a bit field with bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

Remarks

If the value of the SendKeyboardEvents property is true, this event occurs when the Windows Media Player control has focus and the user releases a key. If SendKeyboardEvents is false, this event does not occur.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.KeyDown
  • Player6.KeyPress
  • Player6.SendKeyboardEvents


Player6.MarkerHit

This event occurs when playback reaches a marker.

Syntax

JScript

<SCRIPT FOR="MediaPlayer" EVENT="MarkerHit(lMarkerNum)" LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_MarkerHit(lMarkerNum)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lMarkerNum

Long value specifying the number of the marker that was reached.

Remarks

This event does not occur if the file is being scanned (fast-forward or fast-reverse).

See Also

  • Playback Methods and Properties


Player6.MouseDown

This event occurs when the user presses a mouse button.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="MouseDown( iButton, iShiftState, fX, fY )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_MouseDown( iButton, iShiftState, fX, fY )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iButton

Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

iShiftState

Integer value specifying a bit field with bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

fX

Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

fY

Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event occurs only if the value of the SendMouseClickEvents property is true.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.Click
  • Player6.DblClick
  • Player6.MouseUp
  • Player6.SendMouseClickEvents


Player6.MouseMove

This event occurs when the user moves the mouse pointer within the Windows Media Player control window.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="MouseMove( iButton, iShiftState, fX, fY )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_MouseMove( iButton, iShiftState, fX, fY )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iButton

Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating which buttons were being pressed at the time the event occurred.

iShiftState

Integer value specifying a bit field with the least significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys were pressed at the time the event occurred.

fX

Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

fY

Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event occurs only if the value of the SendMouseMoveEvents property is true.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.SendMouseMoveEvents


Player6.MouseUp

This event occurs when a mouse button is released.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="MouseUp( iButton, iShiftState, fX, fY )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_MouseUp( iButton, iShiftState, fX, fY )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

iButton

Integer value specifying a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.

iShiftState

Integer value specifying a bit field with the least significant bits corresponding to the SHIFT key (bit 0), the CTRL key (bit 1), and the ALT key (bit 2 ). These bits correspond to the values 1, 2, and 4, respectively. The shift argument indicates the state of these keys. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed.

fX

Single value specifying the x-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

fY

Single value specifying the y-coordinate of the mouse pointer relative to the upper left-hand corner of the image window.

Remarks

This event occurs only if the value of the SendMouseClickEvents property is true.

See Also

  • Capturing Keyboard and Mouse Events
  • Player6.Click
  • Player6.DblClick
  • Player6.MouseDown
  • Player6.SendMouseClickEvents


Player6.NewStream

This event occurs when a new stream begins loading.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="NewStream( )"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_NewStream( )
    <!-- insert script commands -->
End Sub
</SCRIPT>

Remarks

Because of stream buffering, this event can occur before the Windows Media Player control begins playback.

See Also

  • Monitoring Stream Status and Network Reception
  • Player6.EndOfStream


Player6.OpenStateChange

This event occurs when the open state changes.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="OpenStateChange(lOldState, lNewState)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_OpenStateChange(lOldState, lNewState)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lOldState

Long value specifying the previous value of the OpenState property.

lNewState

Long value indicating the new value of the OpenState property.

Remarks

This event occurs only if the value of the SendOpenStateChangeEvents property is true.

See Also

  • Monitoring Stream Status and Network Reception


Player6.PlayStateChange

This event occurs when the play state changes.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="PlayStateChange(lOldState, lNewState)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_PlayStateChange(lOldState, lNewState)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lOldState

Long value specifying the previous value of the PlayState property.

lNewState

Long value indicating the new value of the PlayState property.

Remarks

This event occurs only if the value of the SendPlayStateChangeEvents property is true.

See Also

  • Monitoring Stream Status and Network Reception


Player6.PositionChange

This event occurs when the current media position changes, such as when the user selects (or seeks to) a new media position.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="PositionChange(dblOldPosition, dblNewPosition)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_PositionChange(dblOldPosition, dblNewPosition)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

dblOldPosition

Double value indicating the position before it changed, in seconds.

dblNewPosition

Double value indicating the current position, in seconds.

See Also

  • Playback Methods and Properties


Player6.ReadyStateChange

This event occurs when the ready state changes.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="ReadyStateChange(lReadyState)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_ReadyStateChange(lReadyState)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lReadyState

Long value indicating the current value of the ReadyState property, after it changes. It can have one of the following possible values.

Value | Visual Basic constant | Description
0 | mpReadyStateUninitialized | The FileName property has not been initialized.
1 | mpReadyStateLoading | The Windows Media Player control is asynchronously loading a file.
3 | mpReadyStateInteractive | The Windows Media Player control loaded a file, and downloaded enough data to play the file, but has not yet received all data.
4 | mpReadyStateComplete | All data has been downloaded.

Remarks

After calling the Open method, applications should check the ready state before attempting to call the Play method on the newly opened file. Applications should call the Play method only if the lReadyState parameter equals 3 (mpReadyStateInteractive) or 4 (mpReadyStateComplete).


Player6.ScriptCommand

This event occurs when the Windows Media Player control receives a synchronized command or URL.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="ScriptCommand(sType, sParam)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_ScriptCommand(sType, sParam)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

sType

String value specifying the type of script command.

sParam

String value specifying the value of the script command.

Remarks

Commands can be embedded among the sounds and images of a Windows Media file. A command is 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. The sType parameter specifies the type of command and the sParam parameter specifies the command. The type parameter determines how the Windows Media Player control processes the command parameter. Any type of command can be embedded in a Windows Media stream to be handled by the ScriptCommand event.

One type of command is a URL (Uniform Resource Locator). The Windows Media Player control automatically invokes URL-type commands in your default browser if the InvokeURLs property is true.

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

  1. The control receives the embedded script command.
  2. The ScriptCommand event occurs.
  3. If InvokeURLs is true and the command is a URL-type, the control invokes the specified URL. If the command is a URL-type but InvokeURLs is false, the command is ignored.
  4. All other event types are processed by the Media Player by default.

When you author a Windows Media file, you can specify the frame in which the new URL is displayed by appending 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 will be launched in the frame myframe.

Type = "URL"
Param = "http://example.microsoft.com/mypage.html&&myframe"

Other types of script commands automatically processed by the Windows Media Player control include FILENAME, TEXT, EVENT, and OPENEVENT commands. For the FILENAME type, the Windows Media Player control resets the FileName property, attempts to open the specified file, and begins playing the new stream immediately. For the TEXT type, the Windows Media Player control displays the associated text in the captioning window of the Windows Media Player. For the EVENT type, the Windows Media Player control executes instructions defined for the specified event. For the OPENEVENT type, the Windows Media Player buffers the associated EVENT-type command for execution when it receives the corresponding EVENT from the Windows Media stream.

You can embed any other type of command as long as you provide corresponding code to handle it. The Windows Media Player control ignores unknown command types, but still hands them off to the ScriptCommand event.

This event does not occur if the file is being scanned (fast-forwarded or fast-reversed).

Example

The following example first checks whether the received command is a URL. If not, it displays the command in a text box.

Sub MediaPlayer_ScriptCommand( eventType, Param )
  If Not (eventType = "URL") Then      'Not URL?
    TextBox.Text = eventType + ": " + Param   'Show command
  End If
End Sub

This example could be used to display text captions embedded in a Windows Media file. Another approach would be to check for commands of type "CAPTION" and then author Windows Media files with "CAPTION" tags wherever you want to insert captions. You could also send Microsoft® Visual Basic® Scripting Edition (VBScript) commands through a Windows Media file and then build Microsoft® ActiveX® HTML pages on the fly.

See Also

  • Processing Embedded Script Commands


Player6.Warning

This event occurs when the Windows Media Player control encounters a possible problem.

Syntax

JScript

<SCRIPT FOR="MediaPlayer"
        EVENT="Warning(lType, lParam, sDescription)"
        LANGUAGE="JScript">
    <!-- insert script commands -->
</SCRIPT>

VBScript

<SCRIPT LANGUAGE="VBScript">
Sub MediaPlayer_Warning(lType, lParam, sDescription)
    <!-- insert script commands -->
End Sub
</SCRIPT>

Parameters

lType

Long value specifying the type of problem encountered. It can have one of the following possible values.

Value | Visual Basic constant | Description | Parameter
0 | nsNoAudioDevice | The audio playback device is already in use. | Always zero.
1 | nsUnknownStreamFormat | An unknown stream format was received. | The stream number of the invalid stream.
2 | nsPlaylistItemFailure | A file specified in the playlist cannot be played. | The number of the clip in the playlist that failed to play.

lParam

Long value specifying additional information about the warning. Different information is specified for different types of warnings, as listed in the column labeled Parameter in the above table.

sDescription

String value specifying the description of the problem encountered.

Remarks

This event occurs only if the SendWarningEvents property is true.

See Also

  • Error Handling
  • Monitoring Stream Status and Network Reception
  • Player6.SendWarningEvents


Windows Media Player Object Model Version 6.4 Objects

The Windows Media Player Object Model version 6.4 supports the following objects.

Object | Description
ActiveMovie | Returns a Microsoft® Active Movie™ player object, to provide support for backward compatibility.
NSPlay | Returns a Microsoft® NetShow™ Player object, to provide support for backward compatibility.


ActiveMovie Object

This topic applies to Windows Media Player version 6.4 only.

Provides access to properties, methods, and events specific to previous versions of the Microsoft® ActiveMovie™ control.

Syntax

MediaPlayer.ActiveMovie

Remarks

This object is provided for backward compatibility purposes only.

See Also

  • Compatibility Modes
  • NSPlay


NSPlay Object

This topic applies to Windows Media Player version 6.4 only.

Provides access to the Microsoft® NetShow™ Player properties, methods, and events specific to previous versions of the NetShow Player control.

Syntax

MediaPlayer.NSPlay

Remarks

This object is provided for backward compatibility purposes only.

See Also

  • ActiveMovie
  • Compatibility Modes


Windows Media Player Skins

Microsoft® Windows Media™ Player provides a programming platform to create custom skins. Skins are sets of scripts, art, media, and text files that can be combined to create a new appearance for Windows Media Player. Using skins, you can change not only the way Windows Media Player looks, but how it functions. Not just where the knobs are and what they look like, but what they do, given the limits of the underlying Windows Media Player core technology.

Skin technology is very different from other kinds of programming: essentially you will be mixing programming and art in equal parts. You do not need to be an expert programmer (not much more than you already know if you have created Web pages and done some simple scripting), and neither do you need to be an artist (as long as you can use an art manipulation program such as Adobe Photoshop). You'll be using XML (similar to HTML), Microsoft JScript (similar to Microsoft Visual Basic and other high-level languages), and whatever art programs you choose.

The skins documentation contains the following three sections.

Section | Description
About Skins | Discusses the theory of skins in abstract terms. You are advised to at least browse this section because skin technology is so different from other kinds of programming. This section tells you why and how things work, but only skims over the details.
Guide to Skin Creation | Explains what you need to do to create a skin. You will probably want to read this section because it covers the details of creating simple skins, and then more complicated skins that use particular skin elements. This section also includes tutorials on creating the art needed to create skins.
Skin Programming Reference | Contains reference entries for every element and attribute supported by skins. Read the topics that explain the functionality that you want to use.


About Skins

Microsoft® Windows Media™ Player lets the user choose from a variety of standard skins, each one providing an additional visual experience that enhances listening and viewing pleasure. Windows Media Player comes with several skins to choose from, but it is relatively easy to create and distribute custom skins.

Even though skins can be quite elaborate and artistic, the basic technology is easily learned. Skins are nothing more than a collection of one or more files of computer art that is organized by a text file that tells Windows Media Player how to use the skin. Even if you do not consider yourself an artist, you can use a variety of art programs to modify existing art or create simple art of your own. For example, using the drawing tools and clip art supplied with Microsoft® PowerPoint®, you can create artwork by just dragging and dropping. Similarly, you do not need to be a programmer to create the text file used to define an individual skin.

One of the reasons that skins are relatively easy to create is that you can look at the individual pieces of art and the source code for any skin, and see how each skin is put together. Several simple example skins will be provided with this SDK, as well as a complete reference for all skin elements and attributes.


Why Make Skins

When someone uses a program in a graphical computer environment such as Microsoft Windows®, the visual options open to them are called a user interface. One of the purposes of Microsoft Windows is to provide a standard user interface so that all programs will operate the same way. For example, Microsoft recommends in the Windows User Interface Guidelines that every program provide a Close button in the upper right hand corner of the main window of the program.

Windows Media Player provides the capabilities for creating your own user interface. If you want to put the Close button in the middle of the screen, you can do that. Perhaps you do not like the way the Close button looks (it looks like an X inside a box); if you want it to look like a skull and crossbones, you can make a user interface where the Close button is just that! Windows Media Player gives you all the tools you need to make a custom user interface for playing music and video: buttons, slider bars, video windows, visualization windows, equalization bars, and so on.

There are several good reasons why you might want to create your own user interface for Windows Media Player. One reason is that you might want to add functionality that is not already in Windows Media Player. For example, you might want to create a player that plays music from playlists that are based on the time of day, so that you have upbeat rock in the morning and slow jazz in the evening. Or perhaps you want to make a skin with a big red button that will stop the music quickly. Windows Media Player does not come with a "play the same song over and over again until my roommate goes crazy" button, but if you want one, you can create it.

Another reason for creating a skin is to make a branded look for Windows Media Player. If you are distributing music from your Web site and use a particular logo, you might want to design a skin that uses your logo to remind people about your site. If you have a rock band, you can make a skin with pictures of your band on it.

And another good reason to make skins is to make something unique that can dress up your desktop. When your friends come over and ask you what that cool program on your screen is, you can say you made it yourself. You can even take a picture of your dog, scan it into your computer, add some buttons, and click on your dog's nose to start music and the tail to stop it. You can create different skins for different kinds of music or have a different skin for every day of the week.


Skin Files

When you see a skin, you are seeing only the surface. Behind the surface are several files that make up the complete skin. Technically speaking, a skin is a group of files, with each file containing a specific kind of information. Here are the types of files you can use to make up a complete skin:

File type | Description
Skin Definition File | The master file that defines how the other files will be used. This is a text file and has the extension .wms.
Art Files | Art files contain the artwork for your skins. You can create your art in layers, for example, putting your buttons in one file and your background in another. You also will be creating special art files, called mapping files, that contain color information used to interpret mouse actions. Both kinds of files are created with standard art programs and use the extensions of .bmp, .gif, .jpg, .png, and so on.
JScript Files | If you want to create more complicated responses to events, you can create Microsoft® JScript® files that contain scripting code. These are text files and have the extension .js.


Skin Definition File

Skin definition files are the traffic coordinators of your skin. Inside this file are the basic instructions for what the skin does and where the other pieces are. There can only be one skin definition file for a skin, and it has the extension .wms (Windows Media Skin). If the skin definition file and related files are collected and compressed into one Zip file, the extension is .wmz (Windows Media Zipped).


XML

The instructions in the skin definition file are written in XML, the eXtensible Markup Language that is an extension to HTML. If you have used HTML to create Web pages, you will find that XML looks very familiar. The XML in the skin definition file uses a set of special element tags to define parts of the skin user interface. For example, the <BUTTON> tag defines how a button will behave, where it will go, and what it will look like.

Each element tag has specific attributes. For example, the BUTTON element has an Image attribute that defines where the picture of the button can be found. This is similar to HTML, where the BODY element will have a BgColor attribute which defines the background color of the body of the HTML page. You can also think of attributes as similar to methods and properties of objects in Microsoft JScript® or other object-based languages. Detailed information about all skin elements and their attributes is included in the Skin Programming Reference section.

XML has a few simple rules that you need to know to create skins. Unlike HTML, XML requires you to follow the rules exactly.

Enclose Elements with Angle Brackets

All elements are enclosed by angle brackets; for example, the Button element is typed

<BUTTON>

You do not need to type the word "Button" in all uppercase, but the convention of typing element names in all uppercase is used in the example code of this SDK.

Put Attributes Before the Closing Bracket

All attributes for a particular element must be included before the closing angle bracket. An attribute consists of the attribute name followed by an equal sign (=) and the value of the attribute in quotes. For example,

<BUTTON image="mysong.wma">

You do not need to type the word "image" in lowercase, but the convention of typing attribute names in lowercase is used in the example code of this SDK. Also note that the value of the attribute is enclosed in quotation marks.

Opening and Closing Elements

Some elements are grouped together inside another element. For example, the BUTTONGROUP element does not make a lot of sense unless you use one or more BUTTONELEMENT elements with it. To make the grouping clear, you need to have an opening and closing tag for each element. The opening tag is just the element name and any related attributes, surrounded by angle brackets. The closing tag is the element name, preceded by a forward slash, (/) and then enclosed by angle brackets. For example, the BUTTONGROUP element opening tag is:

<BUTTONGROUP>

and the closing tag is:

</BUTTONGROUP>

You would put the BUTTONELEMENT tags between the opening and closing BUTTONGROUP element tags. For example:

<BUTTONGROUP>
    <BUTTONELEMENT/>
    <BUTTONELEMENT/>
    <BUTTONELEMENT/>
</BUTTONGROUP>

Closing Off Elements

If an element has no other elements inside it, you must put a forward slash at the end of the element name just before the closing angle bracket. For example, in the code above, each BUTTONELEMENT element has a forward slash to indicate that there are no other elements nested within it.

In other words, you must either have a closing element tag or close off your element with a forward slash.

This is correct:

<BUTTONGROUP>
    <BUTTONELEMENT/>
    <BUTTONELEMENT/>
</BUTTONGROUP>

This is not:

<BUTTONGROUP/>
    <BUTTONELEMENT/>
    <BUTTONELEMENT/>
</BUTTONGROUP>

This is also incorrect:

<BUTTONGROUP>
    <BUTTONELEMENT>
    <BUTTONELEMENT>
</BUTTONGROUP>

because the BUTTONELEMENT tags are not closed off.


Structure

The skin definition file must follow a specific structure. You start with a Theme, create one or more Views, and then define each View with the user interface elements appropriate for the type of View you want to use.

Theme

At the top level, you must start the skin definition file with the THEME element and close with it.

<THEME>
    ...
</THEME>

The THEME element is the root element for your skin. There can be only one THEME element in a skin definition file, and it must be at the top level. THEME elements have specific and ambient attributes, though most of the time you will not need to use them. For more information about these attributes, see the Skin Programming Reference.

View

Each Theme must have at least one View. The View governs the particular image you see on the screen. You may want to have more than one View, so you can switch back and forth. For example, you might want to have a large view for working with playlists, a medium view for watching visualizations, and a tiny view that fits in a corner of the screen.

If you are creating multiple views, you will want to make sure that each view has a unique ID attribute value that will be used to identify the view. You must define the backgroundImage attribute or your view will have no starting image. If you do not want to display a rectangular image, you will probably want to use the clippingColor attribute to define the areas of your skin that will not display, and you will probably want to set the titleBar attribute of the VIEW element.

Each VIEW element can also have one or more SUBVIEW elements. A SUBVIEW element is similar to a VIEW and can be used for parts of your skin that you want to move around, hide, or show. For example, a SUBVIEW element might be used to create a sliding tray that pops out of your skin to display a graphic equalizer. SUBVIEWs can be aligned with the VIEW and have other special relationships to the VIEW.

Initializing the Player

You can set certain initial properties of Windows Media Player by using the PLAYER, SETTINGS, and CONTROLS elements. For example, you could set the volume to an initial level or give a default value for a file name.

The following code shows how to set the URL value in a skin:

<PLAYER
  URL = "file:..\\media\\mellow.wma">
</PLAYER>

Note that file URL is used and that the slashes are escaped by another slash. If you wanted to set the autoStart attribute of SETTINGS to False, you would use the following code:

<PLAYER>
  <SETTINGS
    autoStart = "False">
  </SETTINGS>
</PLAYER>

Note that the SETTINGS element is nested inside the PLAYER element.

Using these elements, the following attributes and events can be specified at design time:

PLAYER

  • url
  • buffering
  • currentitemchange
  • currentplaylistchange
  • error
  • markerhit
  • mediachange
  • mediacollectionchange
  • modechange
  • openstatechange
  • playlistchange
  • playstatechange
  • positionchange
  • scriptcommand
  • statuschange

SETTINGS

  • autoStart
  • balance
  • baseURL
  • defaultFrame
  • enableErrorDialogs
  • invokeURLs
  • mute
  • playCount
  • rate
  • volume

CONTROLS

  • currentMarker
  • currentPosition

Other UI Elements

Once you have defined your THEME and VIEW elements, you must populate your VIEW with specific user interface elements. You do not have to use all the available elements in a skin, just the ones you need.

If an element can be seen by the user, it is called a control. The following controls are available for skins:

  • Buttons
  • Sliders, custom sliders, and progress bars
  • Text boxes
  • Video windows
  • Visualization windows
  • Playlist windows
  • SubView windows

In addition, several elements can be used to further define Windows Media Player actions, but they require visual elements such as buttons or sliders:

  • Video settings
  • Equalizer Settings
  • Visualization settings

Buttons

Buttons are the most popular part of a skin. You can use buttons to trigger actions such as play, stop, quit, minimize, and switch to different view. Windows Media Player provides the skin creator with two types of button elements: the BUTTON element and the BUTTONGROUP element. In addition, there are several predefined types of buttons.

Button element

The BUTTON element is used for stand-alone buttons. If you use the BUTTON element, you must supply an image for each button and define the exact location,in pixels, where you want the button to appear, relative to the background image. One of the advantages of the BUTTON element is that you can change the button image dynamically.

BUTTONGROUP element

The BUTTONGROUP element is used for groups of buttons. In fact, you must enclose each BUTTONGROUP element with a set of BUTTONGROUP tags. Using button groups is easier than using individual buttons because you do not have to specify the exact location for each button. Instead, you supply a separate image map that defines the actions that will take place when the mouse hovers over or clicks an area on your background. Using image maps is easy because you can take the art you created for your background and copy it to a mapping layer in your art program. Using your art program is faster and more precise than trying to define exactly where a non-group button should be placed on your background.

Predefined buttons

There are several predefined buttons. For example, you can use a PLAYELEMENT button to play media files and a STOPELEMENT to stop. See BUTTONGROUP Element and BUTTON Element in the Skin Programming Reference. The IMAGEBUTTON can be used to display images that can change in response to specific events.

Sliders

Sliders are useful for working with information that changes over time. For example, you might use a slider to indicate the amount of music that has already played for a given media. They can be horizontal or vertical, linear or circular, or any shape you can think of. Sliders come in three varieties: sliders, progress bars, and custom sliders.

Sliders

You can use the SLIDER element for volume controls or to allow the user to move to a different part of the media content.

Progress bars

Progress bars are similar to sliders. Progress bars are designed for displaying information that changes, but not data that the user will want to interact with. For example, you might want to use a progress bar to indicate buffering progress.

Custom sliders

A custom slider is provided so you can create controls such as knobs, or do unusual control mechanisms. For example, if you want to create a volume control that wraps around your skin, you can do it with a custom slider. To set up the custom slider, you must create an image map that contains grayscale images to define the locations of the values on the slider. This is relatively easy to do with an art program that has layers.

Text

You can use the TEXT element to display text on your skin, such as song titles.

Video

You can display video in your skin. The VIDEO element allows you to set the size and position of the video window.

You can also allow the user to change the video settings with the VIDEOSETTINGS element. For example, you can create controls to adjust the brightness of the video.

If you do not supply a video element and the content contains video, Windows Media Player will return to Full Mode and your skin will not be displayed.

Equalizer Settings

You can set the filtering for specific audio frequency bands by using the EQUALIZERSETTINGS element. Essentially this means you can boost the bass, tweak the treble, and set up your sounds to match your ears or your living room.

Visualizations

You can display visualizations in your skin. Visualizations are visual effects that change over time as audio is playing through Windows Media Player. The EFFECTS element determines where the visualizations will play, what size the window will be, and which visualizations will be played.

Windows Media Player comes with three standard visualizations: Bars, DotPlane, and Spikes. You can use the BARS element, the DOTPLANE element, and the SPIKES element to define the attributes of each of the three standard visualizations.

You can also use the EFFECTS element to define how custom visualizations are displayed. For more information about creating custom visualizations, see Windows Media Player Custom Visualizations.

Playlists

You can use the PLAYLIST element to allow the user to select an item from a specific playlist.

SubViews

You can use SubView to display secondary sets of interface controls, such as a playlist or video controls.


Art Files

You must create one or more art files for your skin. Without art, the user will have nothing to look at. You could create an invisible skin, but no one would see it! And even then, you would still have to create art files to hold your invisible images, because the skin definition file requires art files for specific elements.

There are three uses of art in skins:

Primary Images

You must create a primary image for your skin. This is what the users will see when they install your skin. The primary image is composed of one or more images that are created by specific skin controls. If you have more than one control, you must specify the z-order. It defines which controls are displayed "in front" of other ones. Each View control will have a background image that you can add other element images to, allowing you to create a primary composite image. You also may have secondary images, such as a sliding tray, that do not display when your skin first appears, but that show up when the user takes some action. These follow the same rules as primary images, in that they are created with a set of controls.

Mapping Images

One of the most powerful features of Windows Media Player skins is that you can use image mapping to trigger events for your skin. Image maps are files that contain special images. The images in an image map file, however, are not meant to be viewed by the user, but are used by Windows Media Player to take action when the user clicks on your skin. In essence, the user cannot see them, but the mouse can. Different controls need different kinds of image maps. For example, if you color part of an image map a specific red value, and the user clicks on the corresponding area of your primary image, a button will fire an event. Color is used to define which events are triggered by clicks in what areas of the skin. This may sound odd, but it allows a great deal of artistic control over the actions that your skin can process.

Alternate Images

You can also set up alternate images to display when a user does something. For example, you can create an alternate image of a button that will be displayed only when the mouse hovers over the button. This is a good way to let users know what they can do, and also allows for a highly discoverable user interface. By using ToolTips and hover images carefully, you can create unusual user interfaces that still give the user feedback on what options are available.


Primary Images

You will want to create primary images for your skin. The primary image is composed of one background image defined by the VIEW element, and any other images that go with specific elements. For example, if you create a BUTTON element, you must include the art for that button, and be sure that it has a higher z-order than the background image.

Creating Art

There are numerous computer applications that will help you create artistic masterpieces, and more are appearing every day. Many people will create skins as part of a team. There are three areas of skin creation that relate to art. You may be one or more of the following creators:

Illustrator

You are an illustrator, fine artist, or painter, and you use programs focused on creating art from scratch, such as Adobe Illustrator and Metacreations Painter. You can draw and paint original images. These images can be used to create original skin art.

Designer

You are a commercial artist, designer, or art director, and you take advantage of programs that will do a lot of the art modification for you, such as Adobe PhotoShop or Jasc PaintShopPro. If you are on a team, someone else may do the original art or you may modify existing art that you obtained through a scanner, clip art collection, or digital camera.

Programmer

You do not create or modify art, but you create the code that uses the art. You may help the illustrator or designer understand the requirements for the art.

The creation process is fluid and the work will probably go back and forth between team members as the skin evolves. You might start out with an image created by an illustrator, the programmer may request image maps, and the art director may make modifications to the art based on technical suggestions from the programmer.

Similar types of teams have evolved for games and Web pages. It is unusual to have someone with all three skills, since each skill requires experience and training. All that matters is that you identify the skills needed and find the person to do the job, even if it turns out to be you for everything!


Mapping Images

Mapping images are used for specific controls to specify which regions will respond to mouse clicks and to determine which controls receive which events. The mapping image must be the same height and width as the primary image and should be registered exactly so that the images in both files are lined up exactly. For this reason, an art program such as Adobe PhotoShop is recommended because you can work in layers to be certain your images are perfectly aligned.

Different controls require different types of mapping. A ButtonElement control needs a map that has a different color for each button. The colored areas in the mapping file must correspond to the areas of the buttons you want to map.


Alternate Images

Alternate images are images that are not seen when the skin is initially displayed, but become visible in response to mouse events. For example, you can set up the skin so that when a mouse hovers over a specific area, the art in that area will change. This can inform users visually that they can click on an area to do something. You might also use an alternate image when the user clicks on an area to give them visual feedback that the click was received by Windows Media Player.


Art File Formats

The following art file formats are recognized by Windows Media Player for skins:

BMP

Microsoft Windows Bitmap images are recommended because they offer the most control over the exact image and colors. This format is designed to be used with Microsoft Windows applications, and Windows Media Player skins are Microsoft Windows applications.

JPG

Compressed image format used for Web pages.

GIF

Compressed image format used for Web pages. Animated GIFs are supported.

PNG

Compressed image format used for Web pages.

Note If you use one of the compressed file formats that defines a color as transparent to a Web browser, do not define a color as transparent in the image file. Use a visible color to represent transparent areas in your image, and then define that color as transparent in the skin definition file. For example, if you create a gif file with some areas transparent, they will not be transparent in your final image and you will not be able to use the color you set as transparent in your gif file for the transparency color in your skin.


Simple Art Example

Three art files are needed to create a simple skin with two buttons. A primary image and a mapping image are required, and an alternate image provides a visual cue to the user that a button is clickable.

These art files were created in Adobe Photoshop but any art program could be used. An art program that uses layers is easier to work with because you will want to make sure that your primary, mapping, and alternate images all are the same size and line up with each other.

The detailed instructions on creating the art are in the Guide to Skin Creation.

Primary Image

The primary image is a simple yellow oval with two buttons, a pink one to start Windows Media Player and purple button to stop it. The background is a slightly darker yellow than the oval.

The primary image was created in Adobe Photoshop from the following images, each in a separate layer. First an oval was created with a layer bevel and emboss effect.

Then the two buttons were created, also with layer bevel and emboss effects.

Next the image background was created. A slightly darker yellow was chosen so that any anti-aliasing between the oval and the background will not be noticed. The color value is #CCCC00. This number is shown in the Photoshop Color Picker dialog box.

The layers that contained these images were made visible and saved as a copy in the bitmap (bmp) format, creating the primary image. The primary composited image will be used by the backgroundImage attribute of the VIEW element.

Mapping Image

A mapping image is needed to specify when and where a skin is clicked. A mapping image was created with a red area and a green area.

The green area will be used to identify the area on the skin that will start Windows Media Player and the red area will be used to stop it. The mapping image is the same size as the primary image.

The mapping image was created by copying the button layer to a new layer and turning off the bevel and emboss effect. Flat images are needed for mapping because Windows Media Player will be looking for single color values in each area. It can only search for a color you define, for instance red (#FF0000), and if your image has a bevel or other effect, not all of it will be the exact red you need. To make the mapping buttons an easy color to remember, the images were filled with pure red and pure green, but any color can be used. You will need to remember the color numbers in your map so that they can be entered in the XML skin definition file. In this case, red is #FF0000 and green is #00FF00.

Then, with only the new layer visible, the image was saved as a copy to a bitmap (bmp) file. It will be called by the mappingImage attribute of the BUTTONGROUP element.

Alternate Image

Alternate images are not required but are very useful to give visual cues to the user. In this case, a hover image is recommended so that the user knows what areas can be clicked on.

An alternate image was created with two yellow buttons.

The alternate image was created by copying the original button layer to a new layer and then changing the fill color to yellow. The bevel and emboss effect was kept. Then a new layer was created and images were added: the arrow indicates "play" and the square indicates "stop". Then, with only the new yellow button and type layers visible, the image was saved as a copy to a bitmap file.

The result is that when the mouse hovers over an area defined by the mapping image, the hover image will be displayed, alerting the reader that if they click on that spot, they can play or stop Windows Media Player.

Final Image

Here is the final image of the skin:

And this is the image you will see if you hover over the pink button on the right:

Hover over right button

XML Code for the Art Example

The details of how to write XML code are given in the Guide to Skin Creation, but to show how little code is needed to create a working skin, here is the code for the artwork in this example. Predefined buttons are used for the play and stop functions. You must load a file or playlist from the Windows Media anchor . When Windows Media Player view shifts to Compact Mode, a small box appears in the lower right hand corner of the screen. This box is called the anchor and clicking on it gives you the minimum functionality needed, in case a skin does not provide a way to return to Full Mode. The user can switch between modes using the View menu if in Full Mode or the anchor if in Compact Mode.

<THEME>
    <VIEW
        clippingColor = "#CCCC00"
        backgroundImage = "background.bmp"
        titleBar = "false">

        <BUTTONGROUP
            mappingImage = "map.bmp"
            hoverImage = "hover.bmp">

        <PLAYELEMENT
            mappingColor = "#00FF00"/>

        <STOPELEMENT
            mappingColor = "#FF0000"/>

        </BUTTONGROUP>
    </VIEW>
</THEME>


JScript Files

JScript files are loaded with the scriptFile attribute of the VIEW element. They must be text files and should use the file extension .js. If you have a JScript file that has the same name as the skin definition file, the JScript file will be loaded at the same time as the skin definition file. For example, if you have a skin definition file named laure.wms, and you have a JScript file called laure.js, the laure.js file will be automatically loaded.

You can use Microsoft JScript to create elaborate functionality behind your skin. By creating functions in JScript, you can do almost anything imaginable with skins. For example, you could use a different playlist for every day of the week, but always have the same one on Friday. See Using JScript for more information about using JScript with skins. Note that VBScript, which can be used when embedding the Windows Media Player control in a Web page, is not supported for use with skins.


Writing Code

If you create a skin using only elements and attributes, all you will have is a pretty picture. The real power of skins comes from being able to respond to events. You want your skin to be able to do something when the user clicks on a button, and you will also want to respond to changes that happen to Windows Media Player, such as the progress of the media file that is playing.


Handling Events

Aside from the XML code that you write to initialize attributes for your skin, the primary code you write is JScript code to handle events. Events are either external or internal; that is, they come from the user or from Windows Media Player.


External Events

When users click a button or press a key, you can respond to their input with event handlers. An event handler is a section of code that runs whenever the event is triggered.

The following events are supported by skin elements:

  • load
  • close
  • resize
  • timer
  • click
  • dblclick
  • error
  • mousedown
  • mouseup
  • mousemove
  • mouseover
  • mouseout
  • keypress
  • keydown
  • keyup

See the Skin Programming Reference for more details about specific events.

A typical external event handler would name the event and define the code that will run. For example, if you want to create code to start Windows Media Player when the user clicks on a button, you would put the following line in your button code.

onclick = "JScript: player.URL = 'file:laure.wma' ; "

This will play the file named laure.wma. Note that you add the word "on" to specific events.


Internal Events

You can detect changes that occur in Windows Media Player or changes in your own skin. These can be changes in Windows Media Player object properties or methods, changes in skin attributes, and so on.

Player Property Changes

You can process changes in Windows Media Player by using the wmpprop listener. You must set up the listener as a value of an attribute. Put the value in double quotes, and start with the word "wmpprop" followed by a colon. Then you include the property you want to listen to. When the property changes, the value of the attribute will change also. For example, to have a slider element value change whenever the value of the currentPosition attribute changes, type the following:

<SLIDER id="mySlider" value="wmpprop:player.Controls.currentPosition" />

Important Do not use wmpprop on Windows Media Player methods. Unexpected results may occur.

Windows Media Player Method Changes

You can make your skin respond to the availability of methods on Windows Media Player using wmpenabled and wmpdisabled. These are used similarly to the wmpprop listener except that you can only use these on methods of the Control object that are supported by the isAvailable method.

For example, you could enable a button only when the Play method is enabled, using code like this:

<BUTTON ... enabled=”wmpenabled:player.Controls.Play();” />

Important Do not use wmpenabled or wmpdisabled on Windows Media Player properties. Unexpected results may occur.

Skin Attribute Changes

You can respond to changes in your skin attributes in one of two ways, by using wmpprop or the _onchange event.

You can use wmpprop to listen for changes in your own skin. For example to show the Slider value in a text box, you could type the following:

<TEXT ... value="wmpprop:mySlider.value">

You can use the _onchange event to process events inside an element. You must attach the name of the attribute you want to track to _onchange. For example if you want to track the value of a text box, you would type:

value_onchange

and then assign a JScript string that you want to run when the value changes. For example, to respond to a change in the value of a text box that can be used to adjust the volume of Windows Media Player, type the following inside your Text control as an attribute:

value_onchange = "JScript: player.Settings.Volume = myText.value"


Writing Event Code

Events are treated similarly to attributes. You must give the event a value, and the value is the code you want to run when the event happens. The word "on" is added to the front of the event name; for example, the click event will become onclick.

The event value is in double quotes and starts with the word JScript followed by a colon. The code you want to run comes next, followed by a semicolon and the closing double quotes. For example, to stop playing when the user clicks on a button, type the following as an attribute in your BUTTON element code:

onclick = "JScript: player.Controls.Stop() ; "

If you have a code that requires quotes, use single quotes. Care must be taken when using quotation marks so that they are balanced properly. Here is an example of using both types:

onclick = "JScript: player.URL = 'file:..\\laure.wma' ; "

You can also change attributes of your skin when handling an external event. For example, to close a view named myView, you could type:

onclick = "JScript: myView.close() ;"


Secondary Events

You can determine what other events are taking place when a specific event is triggered. For example, when a mouse button is clicked, you may want to know whether the ALT key was down at the same time.

Event Attributes

The following event attributes are supported for skins:

  • altKey
  • button
  • clientX
  • clientY
  • ctrlKey
  • fromElement
  • offsetX
  • offsetY
  • screenX
  • screenY
  • shiftKey
  • srcElement
  • toElement
  • x
  • y
  • keyCode

For more information about these attributes, see the Skin Programming Reference.

Using Secondary Events

You can only process event attributes in JScript code. You must use the following syntax:

event.eventattributename

where eventattributename is the name of the event attribute. For example, to determine whether the ALT key was pressed during a click event, you could use the following lines in your JScript code:

wasAlt = event.altKey ;
if (wasAlt = "True") ...


Using JScript

Windows Media Player 7 or later requires Microsoft® Internet Explorer version 4 or later. When writing code, do not assume that the user's machine will contain a version of Microsoft® JScript® later than 4.0.


Working with the Player

When using Microsoft JScript to access methods and properties of Windows Media Player, you must use the name "player" for the name of the control. For example, to reference the Stop method, you must type:

player.Controls.Stop()

The player global attribute is the key to accessing the Windows Media Player control through skin scripting. Through this attribute, all the objects of the Windows Media Player control become accessible for run time modification through their properties and methods. Additionally, the PLAYER element is available in order to specify event handlers and the url attribute at design time.


Event Handlers

Microsoft JScript is used to process events in the skin definition file. See Handling Events for more information about event handlers.

You can have more than one line of code in an event handler, but care must be taken not to exceed the line length that JScript permits. Separate the lines by semicolons.

onclick = "JScript: player.URL = 'file:cool.wma' ; myText.value = 'Playing'; "


Calling Functions

If you need to call more than a few lines of code, you can load a script file using the scriptFile attribute of the VIEW element, and call the functions in the script. You can load more than one file per view; for example:

scriptFile = "myfile1.js ; myfile2.js ; myfile3"

After the script files are loaded, you can call functions in them from inside your View section. For example, to call a function called myfunction when something is clicked, type:

onclick = "JScript: myfunction()"

Note If you have more than one view, only the functions in files loaded into the current view are available to the XML and JScript code running with the current view. Files loaded in other views are not in scope with the current view.


Debugging Code

You often will want to see what is happening inside your skin. You can do this through a text control or through a log file.

You can create a TEXT element and place it on a part of your skin temporarily. For example, you could use the following code to create your TEXT element:

        <!-- debugging control -- remove later -->
        <TEXT
            id = "debug"
            foregroundColor = "white"
            backgroundColor = "black"
            value = "debug"
            top = "100"
            left = "50"
            height = "15"
            width = "100"
            z-order = "5" />
        <!-- end debugging control -->

Then, for example, if you want to see the current position of the media content in Windows Media Player, you could use code similar to the following to display the current position in the text box.

<PLAYER
    id = "myplayer">
    <CONTROLS
        id = "mycontrols"
        currentPosition_onchange="value=player.controls.currentPosition"/>
</PLAYER>


Submitting Your Skin

Once you've created and tested your skin, you may want to distribute it to the world. Make sure that you are not violating any copyrights and use only original art or art that does not have a copyright. Before you distribute your skin, ask everyone you know to try out your skin first. Think of all the different ways people can interact with your skin. You want to find and fix any problems before you send it out to the world.

Consult the Windows Media Web Gallery for more information on how to distribute your skin.


Referencing Skins in URLs

If you use a URL to load a media file that will be played by Windows Media Player, you can request that a particular skin be used with that file. If the skin is already installed on the user's machine, it will be used; otherwise the previous skin will be used.

To request a skin, add the following to the end of the URL:

?WMPSkin=skinname

where skinname is the name of the skin you want to request. Do not use quotes around the name of the skin.

For example, to request the headspace skin be used, type the following http URL:

http://myserver/mymedia.wma?WMPSkin=headspace

where myserver is the name of a server and mymedia.wma is the name of a media file.


Borders for Windows Media Player

A border is similar to a skin, but instead of replacing the user interface for the compact mode of Windows Media Player, a border is embedded in the Now Playing pane of the full mode Windows Media Player.

By using the Windows Media Download file format (WMD), you can include content with a border, paving the way to multimedia applications.

A sample WMD file that includes a border and embedded content is included in the samples directory of this SDK.

Creating a Border

A border is created the same way as a skin. The only difference is that the skin is embedded inside the Now Playing pane. This means that the skin size cannot be calculated and that all skin elements must be relative. If the end user resizes Windows Media Player, portions of the border may be clipped off and not seen.

Loading a Border

A border is loaded when a Windows Media metafile that uses the SKIN element is loaded. The HREF attribute of the SKIN element must reference a skin. A typical SKIN element would look like this:

<SKIN HREF="myborder.wmz">

For more information, see SKIN Element.

Including Content with a Border

You can include content with a border by using the Windows Media Download file format (WMD). Follow these steps:

  1. Create the border. Take care to create it in such a way that resizing will not ruin the composition of the border. For example, do not include a background file; make the background transparent so that a visualization could run behind it.
  2. Compress the skin contents (art, JScript files, WMS text file) into a WMZ file.
  3. Create a Windows Media Metafile (ASX) that references the compressed border file (WMZ). The metafile can include playlist information with metadata for art and URLs for specific content.
  4. Assemble the content (WMA, WMV, and so on).
  5. Compress the compressed border, metafile, and content into one file and give it a .wmd file extension.

Using a Border

After you have created the Windows Media Download file, all that the end user has to do is double-click on it. The file will be downloaded to the end user's computer. The files inside the package will be unpacked, the playlist will be added to the playlists, the border will appear in the Now Playing pane of the full mode Windows Media Player, and the first item on the new playlist will begin playing.

Border Samples

To see a sample of a complete working border, click the Start button, then point to Programs, then Windows Media, and then click Windows Media Player SDK samples. You must first install the Windows Media Player SDK to use the samples. If you have not already installed it, click the following link:

Install Windows Media Player SDK


Guide to Skin Creation

This guide is a series of detailed explanations of how to create different kinds of skins. For more general information on skins, see About Skins. For specific details about every attribute, method, and event used in skins, see the Skin Programming Reference. As you get more involved in the programming of your skin, you may want to read the part of this SDK covering the Windows Media Player ActiveX control.

In this guide, instructions for creating the art will be given for Adobe Photoshop 5.5, a popular art manipulation program. The specific instructions may be different if you have a similar art program such as Jasc Paint Shop Pro or Sonic Foundry Viscosity, but the concepts will be the same. Photoshop was chosen for two reasons: it is the most popular art program for commercial artists, and it works with layers. As you will see in the tutorials, layers are very useful for skin creation.

This guide will cover the following tasks.

Task | Description
Building Your First Skin | A walk-through of a simple skin that starts and stops Windows Media Player.
Adding a Playlist | How to use a simple playlist.
Choosing Files | How to pick files with an open file dialog box.
Adding a Video | How to put a video window into your skin.
Adding a Visualization | How to add visualizations.
Adding a Slider | How to use a slider to track the progress of your media content ... and let the user change it!
Creating a Custom Slider | How to control the volume with a custom slider.
Other Skin Samples | See the samples section of the SDK.


Your First Skin

As explained in greater detail in About Skins, a skin is defined in a skin definition file, and requires one or more supporting art files, Microsoft® JScript® files, and media files. This tutorial for a very simple skin requires only the skin definition file and three art files. You will go through the following four steps:

  1. Creating the primary art file
  2. Creating the mapping file
  3. Creating the hover image
  4. Creating the skin definition file


Creating the Primary Art File

The primary art file will contain the art that the user of your skin first sees. In this case, you will be creating images in different layers of your art program. The reason for using layers is that you will copy specific layers later to create map files and alternate art files.

To create the primary art file, you will create the following layers in the following order:

Skin background layer

This is the color that will be transparent when the skin is displayed. Create a layer for this first, but choose the final color of this layer after you chose a color for the skin container layer. This color should be similar to, but not the same as, the skin container layer, to hide any anti-aliasing effects.

Skin container layer

This is the image that will form the outline of your skin and will be what the user sees. It also will be the container for the two buttons in this example. Think of your skin as a container for user interface controls such as buttons, sliders, and so on. In this example, the container is a yellow oval.

Play and Close button layers

These are the two user interface controls that this example uses. You will put them in separate layers so that you can easily adjust them or copy them later.

Before you create your layers, you must create the file that will hold your layers. Start up Photoshop and create a new file that is 100 pixels high and 200 pixels wide. The file used to create the art for this sample is called tiny.psd and is included with the SDK.

All instructions are given in terms of Photoshop, but any other art program can be used to create skins as long as you can save to one of the file formats supported by the Windows Media Player (BMP, GIF, JPG, and PNG). You will find skin creation easier if you use an art program that has layers, such as Adobe Photoshop, Jasc Paint Shop Pro, or Jedor Viscosity. Layers are exteremely useful because images must properly aligned for image mapping and display of alternative images.

Skin Background Layer

Create a new layer and name it Skin background. This will become the transparency color you will define in the skin definition file. Wait until the color for the skin container is chosen before filling the skin background layer with a specific color.

Skin Container Layer

Next create a new layer and call it Skin container. This will define the edges of your skin and will be the container for the buttons.

Choose a foreground color for the shape, using the Web color sliders. In this example, the color "#DBDD11" was chosen.

Next create an oval shape. The easiest way is to use the Eliptical Marquee tool and create an oval selection. When you have created an oval selection that is the size and shape you want, fill the selection with the foreground color and deselect the selection.

Finally, to make this look a bit more interesting, apply the layer effect of Bevel and Emboss with the default values.

Your skin container layer should look like this:

Skin container layer

Background Skin Color

Now that you have chosen a foreground color for your skin container shape, you can choose a similar color for your skin background layer. You do not want the exact same color, or your skin container will be transparent also. In fact, be sure you do not use this exact color anywhere else in your skin, even in photographs, because wherever this color appears, the desktop image will appear instead.

You want a color close to the skin container color to avoid anti-aliasing effects. For example, if you have a black background, some bits of black may show up around the edge of your skin. By choosing a color close to the color of the skin container, any stray pixels that show up in the anti-aliasing process will be unnoticed.

Anti-aliasing is the process of smoothing the edges of slanted or curved shapes. Anti-aliasing creates new colors, for pixels along the edges of a shape, that are a blend of the foreground color and the background color. Some of these in-between colors can cause pixels to be missed when the background color is made transparent.

Your skin background layer should look like this:

Background skin layer

Play and Close Button Layers

Create a new layer and name it Close button. Using the Eliptical Marquee selection tool again, create a circle and position it on the left side of the overall image. Turn on the visibility of the skin container file to help place the selection.

When you are satisfied with the placement, fill the selection with any color (except the color of the skin container or the skin background). In this example, a purple color was chosen. You do not need to remember the number of the color. Then deselect the selection and apply another default Bevel and Emboss layer effect. If you want to apply non-layer effects to your button, make a copy of the original for later use in mapping.

Your Close button should look like this:

Create a new layer and name it Play button. Use the same techniques you did for the Close button, but give it a different color. In this case, a pink button color was chosen, but any color can be used as long as it is not the same color as the skin container (because it would blend into the container) or the skin background color (because it would become transparent).

Your Play button should look like this:

Combine Layers and Save

You are now ready to create the primary art file. Hide all layers and then show only the following layers, in this order (top to bottom):

Play button

Close button

Skin container

Skin background

Save to a new file using the Save a Copy command from the File menu. Select the BMP option in the Save As portion of the Save a Copy dialog box and type a file name that you will refer to later in your skin definition file. Ideally you should save this in the same directory as your skin definition file. For example, you could call this background.bmp. Choose the default settings and save the file.

Your primary art file should look like this:

Primary art file

You will use this file name as the value for the backgroundImage attribute of the VIEW element in your skin definition file.


Creating the Mapping File

Once you have created the pieces of your primary art file, it is relatively easy to create a mapping file. You will create the new mapping file by combining the art from the two button layers you already created.

  1. You will need to take the two buttons you created for the primary art file and copy them to a new layer. Use the following steps:Copy the Close button layer, remove any Layer effects, and rename it Close map. The art should look flat, with no bevels.
  2. Use the Color Picker to create a foreground color of pure red. Be sure the color number value is "#FF0000". Then use the Paint Bucket tool to fill the inside of the circle of the Close map layer.
  3. Copy the Play button layer, remove any Layer effects, and rename it Play map. Again, the art should look flat. You do not want any effects in the mapping layer because you are just defining regions of the bitmap that Windows Media Player will use to determine where the mouse performs an action and what you want to do with it.
  4. Use the Color Picker to create a foreground color of pure green. Be sure the color number value is "#00FF00". Then use the Paint Bucket tool to fill the inside of the circle of the Play map layer.

You are now ready to create the mapping art file. Hide all layers, and then show only the following layers, in this order (top to bottom):

Play map

Close map

Save to a new file using the Save a Copy command from the File menu. Select the BMP option in the Save As portion of the Save a Copy dialog box and type a file name that you will refer to later in your skin definition file. Ideally it should be in the same directory as your skin definition file. For example, you could call this file map.bmp. Choose the default settings and save the file.

Your mapping file should look like this:

As you might guess, the green area will be used to determine when to make Windows Media Player start and the red area is for telling it to stop. Any two colors can be used, as long as you use the color numbers when you set up the skin definition file. Be sure the colors in the map are pure colors for the region you want to use and have distinct edges. A pure color would be one where every single pixel in the area has the same color value. Using an effect may blur or distort the edge, thereby slightly modifying the colors of some of the pixels. The mapping file is only seen by the mouse, not a human, so do not bother decorating it, and remove any layer effects you may have carried over from other layers.

When you save your file, the file name you choose will later be used as the value for the mappingImage attribute of the BUTTONGROUP element in your skin definition file.


Creating the Hover Image

The primary image of this skin is two buttons sitting on an oval. To give the user a clue on what to do, you can add hover images. These are alternate images that are displayed when the user hovers a mouse over a button. The hover buttons will also contain the play and stop VCR control symbols so that users will know exactly what they can do. Using hover images allows you to create complex, self-documenting, artistic skins.

To create the hover image, you will need to take the two buttons you created for the primary art file, copy them to new layers, and add further layers for the text. Use the following steps:

  1. Copy the Close button layer and rename it Close hover.
  2. Use the Color Picker to create a foreground color of a light yellow (#CCFF33). This was chosen to contrast with the button colors. Then use the Paint Bucket tool to fill the inside of the circle in the Close hover layer.
  3. Copy the Play button layer and rename it Play hover.
  4. Use the Paint Bucket tool to fill the inside of the circle in the Play hover layer with the same color as the Close hover circle.
  5. Create a new layer and name it Close square. Use the Color Picker to create a foreground color of dark blue. Use the pen tool to draw a square, turn it into a selection, fill it, and delete the path. Using the Move tool, move the square and center it over the Close hover button.
  6. Create a new layer and name it Play triangle. Use the pen tool to create the triangle for "Play" using the same techniques you did to create the Close square layer. Center it over the Play hover button.

You are now ready to create the hover art file. Hide all layers, and then show only the following layers, in this order (top to bottom):

Play triangle

Close square

Play hover

Close hover

Save to a new file using the Save a Copy command from the File menu. Select the BMP option in the Save As portion of the Save a Copy dialog box, and type a file name that you will refer to later in your skin definition file. Ideally you should save this in the same directory as your skin definition file. For example, you could call this hover.bmp. Choose the default settings and save the file.

Your hover art file should look like this:

The yellow hover button will show in place of the normal button. If you hover over the right button in your skin, the yellow button labeled "Play" will appear, and if you hover over the left button, the user will see "Close". The two hover images will never both be displayed at the same time, because the mouse cannot hover over both buttons at the same time. You must turn hovering on and have a hover art file that matches the areas of the mapping files to areas of the hover file.

When you save your file, the file name you choose will later be used as the value for the hoverImage attribute of the BUTTONGROUP element in your skin definition file.


Creating the Skin Definition File

The skin definition file is a simple text file. You can create skin definition files in any text editor that saves ASCII plain text files, such as Microsoft® Notepad, Microsoft Visual InterDev®, or Microsoft Visual Studio®. Since you will be writing XML, not HTML, you may not want to use an editor for HTML because it may add extra codes you do not want or may tell you about errors that you do not have. You will probably want to avoid word processors such as Microsoft Word; even though Word can save plain text files, you may not want to remember to save as text every time you save.


Skin Definition File XML Structure

The skin definition file is written in XML. One of the important features of XML is that it is completely structured, and is similar to an outline. The XML code is simply a series of elements such as VIEW and BUTTONGROUP. You will start with the elements and then define them with attributes. The rest of this tutorial will give you details on the attributes, but here is the outline of the elements that will be used:

<THEME>
    <VIEW>
        <BUTTONGROUP>
            <BUTTONELEMENT/>
            <BUTTONELEMENT/>
        </BUTTONGROUP>
    </VIEW>
<THEME>

By keeping in mind the simple structure of the elements, you can make sense of the attributes that make each element unique. Details of each element will be covered in the remaining topics of this section. For more information about elements and attributes, see the Skin Programming Reference.


Start with THEME and VIEW

Every skin must have exactly one THEME element and at least one VIEW element.

Using your text editor, create the following text:

<THEME>
    <VIEW
        clippingColor = "#CCCC00"
        backgroundImage = "background.bmp"
        titleBar = "False">

    </VIEW>
</THEME>

Leave some blank lines before the closing VIEW tag because you'll be adding more code here later.

Save your file with any file name you wish, but be sure that the extension is .wms. For example, a typical file name might be skinone.wms.

Every skin must start with <THEME> and end with </THEME>. You can only have one THEME element in your skin, but you must have one.

You must also have at least one VIEW element. You can have more than one VIEW, but this example only has one. You must have an opening <VIEW> and a closing <VIEW>. Notice that the opening </VIEW> tag does not close the tag right away, but includes several attributes before the closing angle bracket (>). The following attributes are used in the THEME element in this example:

clippingColor

You will not always need the clippingColor attribute if the edges of your skin are rectangular. The skin in this example is oval-shaped, so you need a clipping color for the parts of the skin that you want to see the desktop through; essentially all parts outside the oval. In this example skin, we will use a dark yellow, specified as "#CCCC00" in Web format. The reasons for this choice are given in Creating the Primary Art File. Essentially, this value will always be a number that you get from your art program.

backgroundImage

This is the name of the primary art file. It should be the exact file name and path of your primary art file. Only BMP, JPG, GIF, and PNG files are supported, and BMP is recommended.

titleBar

This skin does not have a titleBar, so the value will be "false". You will only want a title bar if you want your skin to have a background color and be rectangular.

Be sure that you put the closing angle bracket (>) after the titleBar value to indicate that you are finished defining the VIEW. Leave a few blank lines before the closing VIEW and THEME tags. You will need the lines for code that you will add later.


Adding BUTTONGROUP

This example uses the BUTTONGROUP element for the coding in the skin definition file. BUTTONGROUP creates an easy way to process mouse events without having to calculate exact locations on the screen and uses color instead of x and y-coordinates.

First you must add the BUTTONGROUP tags to the skin definition file you created. Put them after the THEME tag attributes.

        <BUTTONGROUP
            mappingImage = "map.bmp"
            hoverImage = "hover.bmp">

        </BUTTONGROUP>

Leave a few blank lines above the closing BUTTONGROUP tag for the buttons you will add next.

The following attributes are used to define BUTTONGROUP:

mappingImage

This is the file name of the mapping art file you created before, the one with the red and green circles. This attribute is required for any BUTTONGROUP.

hoverImage

This is the file name of the hover art file you created before, the one with the two yellow buttons that read "Play" and "Close". This is not required, but a hover image helps to provide feedback to the user.


Adding the Play BUTTONELEMENT

Finally, you can add the BUTTONELEMENT elements that connect the visual buttons on the screen to Windows Media Player actions. This is the core of your skin and you can think of it as wiring the surface of the skin to the inner machinery of Windows Media Player.

BUTTONELEMENTs are contained within a BUTTONGROUP. You must always have at least one BUTTONELEMENT inside each BUTTONGROUP.

Put the Play BUTTONELEMENT code after the closing angle bracket of BUTTONGROUP.

        <BUTTONELEMENT
            mappingColor = "#00FF00"
            upToolTip = "Play"
            onClick = "JScript: player.URL='file:laure.wma';" />

The following attributes are used to define the BUTTONELEMENT for the Play button:

mappingColor

This is the color value of a region in the mapping art file you created before. In this case it is the solid green color. This attribute is required for any BUTTONELEMENT. By defining this color, you are telling Windows Media Player to associate this color area with the XML code of this button.

upToolTip

This defines the text that will be displayed if the user hovers the mouse over the button. Do not confuse this with the hover art that will be displayed. A ToolTip is a small balloon caption that takes a moment to appear. The hover art image, however, will appear instantly in whatever color and shape you choose.

onClick

This defines the event that occurs when the mouse clicks on the button. The value of this event attribute is called an event handler and will be either a line of Microsoft JScript code, or a JScript function in an external text file that is loaded by the loadScript attribute of a VIEW. In this case, the JScript code calls the URL method of Windows Media Player, which loads and starts playing a file named "laure.wma". Note that the line ends with a semicolon inside the quotes, which is good JScript coding practice. Note also the use of single quotes inside the double quotes to set off the file name. For more information about JScript, see Using JScript in the About Skins section of this SDK.

Notice that there is no ending BUTTONELEMENT tag. If an element does not enclose another element, you can close it off with the forward slash just before the closing angle bracket. This tells XML that you are finished with that element. For example,

<BUTTONELEMENT></BUTTONELEMENT>

and

<BUTTONELEMENT/>

convey the same information in XML.

The power of skins comes from using event handlers. If the user does something with a mouse, you can handle that event with JScript. Your code can be a single line that makes Windows Media Player do something simple like play, or it can be a complete application written in JScript.


Adding the Close BUTTONELEMENT

The Close button is similar in concept to the Play button, but has different codes and colors.

Put the Close BUTTONELEMENT code after the closing angle bracket of the Play BUTTONELEMENT.

        <BUTTONELEMENT
            mappingColor = "#FF0000"
            upToolTip = "Close"
            onClick="JScript: view.close();" />

The following attributes are used to define the BUTTONELEMENT for the Close button:

mappingColor

This is the color value of the region in the mapping art file you created before. In this case it is the solid red color. This attribute is required for any BUTTONELEMENT. By defining this color, you are telling Windows Media Player to associate this color area with the XML code of this button.

upToolTip

This defines the text that will be displayed when the user hovers the mouse over the button. This is the same as the Play button except that it is labeled "Close".

onClick

This defines the event that occurs when the mouse clicks on the button. The value of this event attribute is called an event handler and will be either a line of Microsoft JScript code, or a JScript function in an external text file that is loaded by the loadScript attribute of a VIEW. In this case, the JScript code calls the close method of the VIEW element using the global attribute view, which closes the view and shuts down Windows Media Player.


Complete Code for Simple Skin

Here is the complete code for the first sample skin:

<THEME>
    <VIEW
        clippingColor = "#CCCC00"
        backgroundImage = "background.bmp"
        titleBar = "false">

        <BUTTONGROUP
            mappingImage = "map.bmp"
            hoverImage = "hover.bmp">

        <BUTTONELEMENT
            mappingColor = "#00FF00"
            upToolTip = "Play"
            onClick="JScript: player.URL='file:laure.wma';" />

        <BUTTONELEMENT
            mappingColor = "#FF0000"
            upToolTip = "Close"
            onClick = "JScript: view.close(); " />

        </BUTTONGROUP>
    </VIEW>
</THEME>

Now you have all the pieces put together. Using PKZip or another program that compresses files into the zip format, zip up your skin definition file, bitmaps, and any media files you want to include, into one file. Rename the zipped file with the extension wmz. Then double-clicking your zipped skin will start it playing.

You can see a similar working simple skin in the samples section of the SDK.


Adding a Playlist

You can use playlists to choose from collections of your audio and video.

Using the artwork from your first skin, you can make a few changes to the skin definition file.

The first step is to use the shell you will use for most skins:

<THEME>
    <VIEW
        clippingColor = "#CCCC00"
        backgroundImage = "background.bmp"
        titleBar = "false">

        <BUTTONGROUP
            mappingImage = "map.bmp"
            hoverImage = "hover.bmp">

    </VIEW>

</THEME>

Now add a second VIEW, which contains a playlist. Place the following code after the </VIEW> of the shell code.

     <VIEW
          id = "playview">
          <PLAYLIST/>
     </VIEW>

You will need to give this second view an ID so you can refer to it later. Add a PLAYELEMENT and a STOPELEMENT. These predefined buttons make life easier.

        <PLAYELEMENT
            mappingColor = "#00FF00" />

        <STOPELEMENT
            mappingColor = "#FF0000" />

Finally, add an onClick event to the PLAYELEMENT to display a playlist in the second view:

            onClick = "JScript: theme.openView('playview');" />

You can see a similar working playlist skin in the sample section of the SDK.


Choosing Files

If you want to choose a file, you can use code similar to the Playlist example, but substitute the following for the PLAYELEMENT section:

<PLAYELEMENT
  mappingColor = "#00FF00"
  onClick = JScript:player.URL=theme.openDialog('FILE_OPEN','FILES_ALL');"
  />

This line will use the openDialog method of THEME to define a URL for the player. You can use this to choose files that are not in playlists.

You can see a similar working openDialog example in the sample section of the SDK.


Adding Video

You can add a video to your file by simply using the VIDEO element and defining where you want the video window to be placed.

Use the same code as you did in the Choosing Files section; all you need to do is add the VIDEO element with the top, left, width, and height attributes.

        <VIDEO
            top = "10"
            left = "80"
            width = "180"
            height = "180"/>

Then when you play a video, it will be displayed in the window. The art for the video sample was modified to make a slightly larger skin. Because layers were used in Photoshop, the buttons were easily moved around and a new set was created very quickly. Only the background image was changed. A fill was used in a blank layer and a bevel and emboss effect was added.

You can see a similar working video skin in the sample section of the SDK.


Adding Visualizations

You can add a visualization window the same way you added a video window. The same skin can be used, but an EFFECTS element is used.

First you must add the EFFECTS element and give it an ID and size:

       <EFFECTS
            id = "myeffects"
            top = "25"
            left = "88"
            width = "180"
            height = "150"/>

Then you can assign the two buttons a previous and next visualization code string:

        <BUTTONELEMENT
            mappingColor = "#00FF00"
            upToolTip = "Next"
            onClick = "JScript:myeffects.next(); " />

        <BUTTONELEMENT
            mappingColor = "#FF0000"
            upToolTip = "Previous"
            onClick = "JScript:myeffects.previous(); " />

The layers and bitmaps were the same ones used in the video example, except that the play arrow was copied and flipped horizontally.

Finally, a simple PLAYER element with the URL attribute was added to choose a song to play.

      <PLAYER
          URL = "file:..\\media\\mellow.wma">
      </PLAYER>

You can see a similar working visualization skin in the sample section of the SDK.


Adding a Slider

You can add a slider to show the current position of the media, and also enable the user to change the position in the current media file.

First you must add the SLIDER element:

<SLIDER
  id = "myslider"
  min = "0"
  max = "wmpprop:player.currentMedia.duration"
  onmouseup = "player.controls.currentPosition = myslider.value; "
  tooltip = "current position"
  height = "10"
  width = "180"
  top = "150"
  left = "88"
  backgroundColor = "red"
  foregroundColor = "blue"
  thumbImage = "thumb.bmp"/>

This sets a maximum value based on the duration of the current media file. This uses a tiny thumb image bitmap that is just a 10 by 10 pixel green square. The background of the slider will be red and the foreground will be blue. When the user drags the thumb image to a new position and lets go of the mouse button, the media will change to that position.

But the slider will not move by itself unless you measure the current position with the currentPosition_onchange attribute of the CONTROLS element, which is embedded in the PLAYER element.

<PLAYER
    URL = "file:..\\media\\laure.wma">

    <CONTROLS
        currentPosition_onchange = "myslider.value = player.controls.currentPosition; "/>

</PLAYER>

When the position of the media changes, this fires an event which then runs the line of code that changes the value of the slider to the current position of the media.

You can see a similar working slider skin in the sample section of the SDK.


Creating Custom Sliders

You can create custom sliders in any shape you want. For this example, a simple strip is chosen, but the actual shape can be anything. Here is the code for the CUSTOMSLIDER element:

<CustomSlider
  top="160"
  left="130"
  min="0"
  max="100"
  toolTip="volume control"
  image="slider.bmp"
  positionImage="graymap.bmp"
  enabled="true"
  value="wmpprop:player.settings.volume"
  value_onchange="player.settings.volume = value" />

This sets up an initial value for the slider. Two new bitmaps are introduced. One is the grayscale bitmap (slider.bmp) that defines which values will be used when clicked on, and the other (slider.bmp) that determines which image will be shown when a particular portion of the grayscale is clicked on.

The initial value is determined by listening to the volume with wmpprop and then the volume can be changed when the user clicks on a portion of the slider that triggers a change in value.

You can see a similar working slider skin in the sample section of the SDK.


Other Skin Samples

To see samples of complete working skins, click the Start button, then point to Programs, then Windows Media, and then click Windows Media Player SDK samples. You must first install the Windows Media Player SDK to use the samples. If you have not already installed it, click the following link:

Install Windows Media Player SDK

.


Skin Programming Reference

The Skin Programming Reference documents the following elements and their associated attributes, methods, and events.

Element | Description
Ambient Attributes | Attributes that apply to all skin elements with exceptions noted.
Ambient Events | Events that are common to all skin elements.
Ambient Event Attributes | Attributes detailing the state of Windows Media Player when an event is fired.
BUTTON | A stand-alone button.
BUTTONELEMENT | A button within a button group.
BUTTONGROUP | A group of button elements.
CONTROLS | Provides access to the Controls object from within a skin.
CUSTOMSLIDER | A customizable slider control.
EFFECTS | An element that contains and controls a collection of effects.
EQUALIZERSETTINGS | An element allowing manipulation of the graphic equalizer.
PLAYER | Provides access to the Player object from within a skin.
PLAYLIST | An element for controlling the appearance of a playlist within a skin.
PROGRESSBAR | Provides a way to display progress information in a horizontal or vertical control.
SETTINGS | Provides access to the Settings object from within a skin.
SLIDER | A slider control.
SUBVIEW | Subsections within a view that can be moved or hidden.
TEXT | A control containing text.
THEME | The main element identifying a skin file.
VIDEO | An element for specifying the appearance of a video window.
VIDEOSETTINGS | An element allowing control of various video settings.
VIEW | Specifies what the UI looks like for each category of media.
Miscellaneous | Specialized attributes and other miscellaneous topics for use in creating skins.


Ambient Attributes

The ambient attributes and method are supported by all appropriate skin elements, except where noted.

The following attributes are ambient.

Attribute | Description
clippingColor | Specifies or retrieves the color to clip out from the clippingImage bitmap.
clippingImage | Specifies or retrieves the region to clip the control to.
elementType | Retrieves the type of the element (for instance, BUTTON).
enabled | Specifies or retrieves a value indicating whether the control is enabled or disabled.
height | Specifies or retrieves the height of the control.
horizontalAlignment | Specifies or retrieves the horizontal alignment of the control when the VIEW or parent SUBVIEW is resized.
id | Specifies or retrieves the identifier of a control. Can only be set at design time.
left | Specifies or retrieves the left coordinate of the control.
passThrough | Specifies or retrieves a value indicating whether the control will pass all mouse events through to the control under it.
tabStop | Specifies or retrieves a value indicating whether the control will be in the tabbing order.
top | Specifies or retrieves the top coordinate of the control.
verticalAlignment | Specifies or retrieves the vertical alignment of the control when the VIEW or parent SUBVIEW is resized.
visible | Specifies or retrieves the visibility of the control.
width | Specifies or retrieves the width of the control.
zIndex | Specifies or retrieves the order in which the control is rendered.

The following method is ambient.

Method | Description
moveTo | Moves the control.


AmbientAttributes.clippingColor

The clippingColor attribute specifies or retrieves the color to clip out from the clippingImage bitmap.

Syntax

elementID.clippingColor

Possible Values

This attribute is a read/write String.

Value | Description
Auto | Default. The color at pixel location 0,0 is used.
any Microsoft Internet Explorer color value | The specified Internet Explorer color is used.

Remarks

The clipping color indicates the regions of the clippingImage (or backgroundImage for VIEW or SUBVIEW) that correspond to transparent, non-clickable portions of the control. The clipping color can indicate multiple regions to be clipped out. A warning is issued if the clippingImage is a JPG to warn of loss of color in JPGs.

The clippingColor attribute is not supported by the PLAYLIST element.

See Also

  • Ambient Attributes
  • AmbientAttributes.clippingImage
  • Color Reference


AmbientAttributes.clippingImage

The clippingImage attribute specifies or retrieves the region to clip the control to.

Syntax

elementID.clippingImage

Possible Values

This attribute is a read/write String indicating the image file name. It has no default value.

Remarks

The clippingImage attribute supports PNG, JPG, BMP, and GIF files (not including animated GIFs). This attribute is useful when you want to display only a part of the control image and not the entire rectangular area. The clippingColor attribute indicates the regions of the clipping image that correspond to transparent, non-clickable portions of the control. The control can therefore be of any shape. For best results, the clipping image should be the same size as the control image.

The clippingImage attribute is not supported by the PLAYLIST, VIEW, and SUBVIEW elements. A clipping image will not work with the VIDEO element if VIDEO.windowless is set to false, nor with the EFFECTS element if EFFECTS.windowed is set to true.

Example

Please see the BUTTONELEMENT.mappingColor attribute for a sample illustrating the use of this attribute.

See Also

  • Ambient Attributes
  • AmbientAttribute.clippingColor


AmbientAttributes.elementType

The elementType attribute retrieves the type of the element (for instance, BUTTON).

Syntax

elementID.elementType

Possible Values

This attribute is a read-only String indicating the name of the element.

Remarks

This attribute is useful in determining the type of element that fired an event and writing a generic event handler for this class of elements.

See Also

  • Ambient Attributes


AmbientAttributes.enabled

The enabled attribute specifies or retrieves a value indicating whether the control is enabled or disabled.

Syntax

elementID.enabled

Possible Values

This attribute is a read/write Boolean.

Values | Description
true | Default. Control enabled.
false | Control disabled.

Remarks

If the control is enabled, it can have a tab stop, and will receive all ambient events. When disabled, the control does not have a tab stop, and does not receive any ambient mouse or keyboard events fired to it. (However, it will continue to receive all other ambient events fired to it.)

See Also

  • Ambient Attributes


AmbientAttributes.height

The height attribute specifies or retrieves the height of the control.

Syntax

elementID.height

Possible Values

This attribute is a read/write Number (long) with a default value of zero or the height of the image specified in the control’s image attribute.

Remarks

If the height specified is smaller than the height of the image provided, then the image will be clipped. If the height is larger than the height of the image, then the click region will go beyond the image boundary. No matter what value is given to this attribute, the image cannot grow beyond its parent VIEW or SUBVIEW.

See Also

  • Ambient Attributes


AmbientAttributes.horizontalAlignment

The horizontalAlignment attribute specifies or retrieves the horizontal alignment of the control when the VIEW or parent SUBVIEW is resized.

Syntax

elementID.horizontalAlignment

Possible Values

This attribute is a read/write String.

Values | Description
left | Default. Aligns the control to the left of the VIEW or parent SUBVIEW when resized.
right | Aligns the control to the right of the VIEW or parent SUBVIEW when resized.
center | Aligns the control to the horizontal center of the VIEW or parent SUBVIEW when resized.
stretch | Aligns the control to left and right margins of the VIEW or parent SUBVIEW when resized. The control stretches to fit when the VIEW or SUBVIEW is stretched. The actual image does not grow or shrink unless it is resizable, but the clickable area grows or shrinks if not bounded by a clippingImage.

Remarks

Unless horizontalAlignment is set to “center”, the control retains its original distance from the specified edge, or from both edges if “stretch” is specified and the control is resizable. If the control is not resizable and “stretch” is specified, the clickable region is stretched instead.

You can set any combination of horizontalAlignment and verticalAlignment. For example, if you want to center a control both horizontally and vertically, set horizontalAlignment=“center” verticalAlignment=“center”.

See Also

  • Ambient Attributes
  • AmbientAttributes.verticalAlignment
  • AmbientAttributes.clippingImage


AmbientAttributes.id

The id attribute specifies or retrieves the identifier of a control. This attribute will support any name permitted by Microsoft® Visual Basic® for Applications.

Syntax

elementID.id

Possible Values

This attribute is a String specified at design time and read-only thereafter. It has a default value of

Unnamed_elementtype_num

where elementtype is the name of the control type, and num is a number corresponding to the position of the control in the sequence of all unnamed controls in the Theme. This number is reset to zero for each new Theme.

Remarks

The value of this attribute is assigned once, and cannot be changed in script.

See Also

  • Ambient Attributes


AmbientAttributes.left

The left attribute specifies or retrieves the left coordinate of the control.

Syntax

elementID.left

Possible Values

This attribute is a read/write Number (long) with a default value of zero. Negative numbers are allowed, in which case the left border of the VIEW or SUBVIEW clips the control.

See Also

  • Ambient Attributes


AmbientAttributes.moveTo

The moveTo method moves the control.

Syntax

elementID.moveTo(newX, newY, time)

Parameters

Parameter | Value
newX | Specifies a new value for X.
newY | Specifies a new value for Y.
time | Specifies the time in milliseconds that it takes for the control to move to its new location.

Return Values

This method does not return a value.

Remarks

This method is useful for animated SUBVIEW elements (for example, if the user clicks on a tray and the controls slide down).

See Also

  • Ambient Attributes


AmbientAttributes.passThrough

The passThrough attribute specifies or retrieves a value indicating whether the control will pass all mouse events through to the control under it.

Syntax

elementID.passThrough

Possible Values

This attribute is a read/write Boolean.

Values | Description
true | Control passes events through to the control under it.
false | Default. Control does not pass events through.

Remarks

This attribute is useful if, for example, a text control sits on top of a button control only to provide labeling. In this case, clicks on the text control must be passed through to the button control.

The passThrough attribute is not supported by the VIEW, SUBVIEW, and PLAYLIST elements. It will not work with the VIDEO element if VIDEO.windowless is set to false, nor with the EFFECTS element if EFFECTS.windowed is set to true.

See Also

  • Ambient Attributes


AmbientAttributes.tabStop

The tabStop attribute specifies or retrieves a value indicating whether the control is in the tabbing order. You set the tabbing order by placing the control in the overall script before or after other control tags.

Syntax

elementID.tabStop

Possible Values

This attribute is a read/write Boolean.

Values | Description
true | Default. Control is in the tabbing order (control will have a tab stop: accessibility requirement).
false | Control is not in the tabbing order.

Remarks

The tabStop attribute is not applicable to the EFFECTS element.

See Also

  • Ambient Attributes


AmbientAttributes.top

The top attribute specifies or retrieves the top coordinate of the control.

Syntax

elementID.top

Possible Values

This attribute is a read/write Number (long) with a default value of zero. Negative numbers are allowed, in which case the top border of the VIEW or SUBVIEW clips the control.

See Also

  • Ambient Attributes
  • AmbientAttributes.id


AmbientAttributes.verticalAlignment

The verticalAlignment attribute specifies or retrieves the vertical alignment of the control when the VIEW or parent SUBVIEW is stretched.

Syntax

elementID.verticalAlignment

Possible Values

This attribute is a read/write String.

Values | Description
top | Default. Aligns the control to the top of the VIEW or parent SUBVIEW when resized.
bottom | Aligns the control to the bottom of the VIEW or parent SUBVIEW when resized.
center | Aligns the control to the vertical center of the VIEW or parent SUBVIEW when resized.
stretch | Aligns the control to top and bottom margins of the View when resized. The control stretches to fit when the VIEW or parent SUBVIEW is stretched. The actual image does not grow or shrink unless it is resizable, but the clickable area grows or shrinks if not bounded by a clippingImage.

Remarks

Unless verticalAlignment is set to “center”, the control retains its original distance from the specified edge, or from both edges if “stretch” is specified and the control is resizable. If the control is not resizable and “stretch” is specified, the clickable region is stretched instead.

You can set any combination of the horizontalAlignment and verticalAlignment attributes. For example, if you want a control to be centered both horizontally and vertically, set horizontalAlignment to “center” and verticalAlignment to “center”.

See Also

  • Ambient Attributes
  • AmbientAttributes.horizontalAlignment


AmbientAttributes.visible

The visible attribute specifies or retrieves the visibility for the control.

Syntax

elementID.visible

Possible Values

This attribute is a read/write Boolean.

Values | Description
true | Default. The control is visible.
false | The control is not visible.

Remarks

This attribute is useful for hiding controls, for example when swapping a pause button for a play button.

If the value is false, the control is not visible and click events are passed to the control behind it. If the value is true, the control is visible and receives the click event itself.

See Also

  • Ambient Attributes


AmbientAttributes.width

The width attribute specifies or retrieves the width of the control.

Syntax

elementID.width

Possible Values

This attribute is a read/write Number (long) with a default value of either zero or the width of the image specified in the control’s image attribute.

Remarks

If the width specified is narrower than the width of the image provided, then the image will be clipped. If the width is wider than the width of the image, then the click region will go beyond the image boundary. No matter what value is given to this attribute, the image cannot grow beyond its parent VIEW or SUBVIEW.

See Also

  • Ambient Attributes


AmbientAttributes.zIndex

The zIndex attribute specifies or retrieves the order in which the control is rendered.

Syntax

elementID.zIndex

Possible Values

This attribute is a read/write Number (long) with a default value of zero. The range is that of a signed long integer.

Remarks

The background bitmap of a VIEW or SUBVIEW has a fixed z index of zero. If you want a control to be behind the background, the zIndex must be set to a negative number.

The z index of a VIEW or SUBVIEW is an absolute index, while the z index of a control is relative to the z index of the VIEW or SUBVIEW that contains it.

The zIndex attribute is not supported by the PLAYLIST element. It will not work with the VIDEO element if VIDEO.windowless is set to false, nor with the EFFECTS element if EFFECTS.windowed is set to true.

BUTTONELEMENT elements use the zIndex of their BUTTONGROUP.

See Also

  • Ambient Attributes


Ambient Events

The following event handlers can be implemented for most skin elements. The ambient event attributes accessed with the event keyword can be used within an event handler to determine the state of the keyboard and mouse at the time of the event.

Event handler | Description
attribute _onchange | When a skin attribute changes value, an event occurs that can be handled by an event handler. The name of the event handler is the name of the attribute followed by an underscore and “onchange”, such as value_onchange.
onblur | Handles an event that occurs when the element loses the keyboard focus.
onclick | Handles an event that occurs when the user clicks the element.
ondblclick | Handles an event that occurs when the user double-clicks the element.
onendmove | Handles an event that occurs when an element completes a moveTo operation.
onfocus | Handles an event that occurs when the element receives the keyboard focus.
onkeydown | Handles an event that occurs when a key is pressed down.
onkeypress | Handles an event that occurs when the user presses an alphanumeric key.
onkeyup | Handles an event that occurs when a key is released.
onmousedown | Handles an event that occurs when the user clicks a mouse button.
onmousemove | Handles an event that occurs when the user moves the mouse pointer while it is over an element.
onmouseout | Handles an event that occurs when the user moves the pointer off the element.
onmouseover | Handles an event that occurs when the user first places the pointer over the element.
onmouseup | Handles an event that occurs when the user releases a mouse button while the pointer is over the element.
onresize | Handles an event that occurs when a control resizes.


attribute_onchange

When a skin attribute changes value, an event occurs that can be handled by an event handler. The name of the event handler is the name of the attribute followed by an underscore and “onchange”, such as value_onchange.

Syntax

attribute_onchange

Example

<SLIDER
  thumbImage = “thumb.gif”
  value_onchange = “JScript: if (value == 100) backgroundColor = ‘green’;”
/>

See Also

  • Ambient Events


onblur

The onblur event handler handles an event that occurs when the element loses the keyboard focus.

Syntax

onblur

Remarks

The onblur event handler is not applicable to the EFFECTS element.

See Also

  • Ambient Events


onclick

The onclick event handler handles an event that occurs when the user clicks the element.

Syntax

onclick

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • Ambient Events


ondblclick

The ondblclick event handler handles an event that occurs when the user double-clicks the element.

Syntax

ondblclick

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • Ambient Events


onendmove

The onendmove event handler handles an event that occurs when an element completes a moveTo operation.

Syntax

onendmove

See Also

  • Ambient Events
  • AmbientAttributes.moveTo


onfocus

The onfocus event handler handles an event that occurs when the element receives the keyboard focus.

Syntax

onfocus

Remarks

The onfocus event handler is not applicable to the EFFECTS element.

See Also

  • Ambient Events


onkeydown

The onkeydown event handler handles an event that occurs when a key is pressed.

Syntax

onkeydown

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • Ambient Events


onkeypress

The onkeypress event handler handles an event that occurs when an alphanumeric key is pressed.

Syntax

onkeypress

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • Ambient Events


onkeyup

The onkeyup event handler handles an event that occurs when a key is released.

Syntax

onkeyup

See Also

  • Ambient Events


onmousedown

The onmousedown event handler handles an event that occurs when the user clicks a mouse button.

Syntax

onmousedown

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • 84Ambient Events


onmousemove

The onmousemove event handler handles an event that occurs when the user moves the mouse pointer while it is over an element.

Syntax

onmousemove

Remarks

This event handler is not applicable to the PLAYLIST element, the VIDEO element when VIDEO.windowless is false, or the EFFECT element when EFFECTS.windowed is true.

See Also

  • Ambient Events


onmouseout

The onmouseout event handler handles an event that occurs when the user moves the pointer off the element.

Syntax

onmouseout

See Also

  • Ambient Events


onmouseover

The onmouseover event handler handles an event that occurs when the user first places the pointer over the element.

Syntax

onmouseover

See Also

  • Ambient Events


onmouseup

The onmouseup event handler handles an event that occurs when the user releases a mouse button while the pointer is over the element.

Syntax

onmouseup

See Also

  • Ambient Events


onresize

The onresize event handler handles an event that occurs when a control resizes.

Syntax

onresize

See Also

  • Ambient Events


Ambient Event Attributes

The following attributes are common to all skin events. They are accessed with the event keyword within an event handler for the element.

Attribute | Description
altKey | Retrieves a value indicating whether the ALT key was down when the event occurred.
button | Retrieves a value indicating which mouse buttons were down when the event occurred.
clientX | Retrieves the x-coordinate of the mouse pointer with respect to the client region of the application window.
clientY | Retrieves the y-coordinate of the mouse pointer with respect to the client region of the application window.
ctrlKey | Retrieves a value indicating whether the CTRL key was down when the event occurred.
fromElement | Retrieves the element the event came from.
keyCode | Retrieves the ASCII key code if a key was pressed when the event occurred.
offsetX | Retrieves the x-coordinate of the mouse pointer with respect to the element firing the event.
offsetY | Retrieves the y-coordinate of the mouse pointer with respect to the element firing the event.
screenX | Retrieves the absolute x-coordinate of the mouse pointer with respect to the screen.
screenY | Retrieves the absolute y-coordinate of the mouse pointer with respect to the screen.
shiftKey | Retrieves a value indicating whether the SHIFT key was down when the event occurred.
srcElement | Retrieves the element that fired the event.
toElement | Retrieves the element the keyboard focus moved to.
x | Retrieves the x-coordinate of the mouse pointer with respect to the application window.
y | Retrieves the y-coordinate of the mouse pointer with respect to the application window.


event.altKey

The altKey attribute retrieves a value indicating whether the ALT key was down when the event occurred.

Syntax

event.altKey

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Indicates the ALT key was in the down position.
false | Indicates the ALT key was in the up position.

See Also

  • Ambient Event Attributes


event.button

The button attribute retrieves a value indicating which mouse buttons were down when the event occurred.

Syntax

event.button

Possible Values

This attribute is a read-only Number (long).

Value | Description
0 | No mouse buttons were down.
1 | The left mouse button was down.
2 | The right mouse button was down.
3 | Both mouse buttons were down.

See Also

  • Ambient Event Attributes


event.clientX

The clientX attribute retrieves the x-coordinate of the mouse pointer with respect to the client region of the application window.

Syntax

event.clientX

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.clientY


event.clientY

The clientY attribute retrieves the y-coordinate of the mouse pointer with respect to the client region of the application window.

Syntax

event.clientY

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.clientX


event.ctrlKey

The ctrlKey attribute retrieves a value indicating whether the control key (CTRL) was down when the event occurred.

Syntax

event.ctrlKey

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Indicates the CTRL key was in the down position.
false | Indicates the CTRL key was in the up position.

See Also

  • Ambient Event Attributes


event.fromElement

The fromElement attribute retrieves the element the event came from. If no element passes an event, the value is NULL.

Syntax

event.fromElement

Possible Values

This attribute is a read-only object.

See Also

  • Ambient Event Attributes


event.keyCode

The keyCode attribute retrieves the ASCII key code if a key was pressed when the event occurred.

Syntax

event.keyCode

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes


event.offsetX

The offsetX attribute retrieves the x-coordinate of the mouse pointer with respect to the element firing the event.

Syntax

event.offsetX

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.offsetY


event.offsetY

The offsetY attribute retrieves the y-coordinate of the mouse pointer with respect to the element firing the event.

Syntax

event.offsetY

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.offsetX


event.screenX

The screenX attribute retrieves the absolute x-coordinate of the mouse pointer with respect to the screen.

Syntax

event.screenX

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.screenY


event.screenY

The screenY attribute retrieves the absolute y-coordinate of the mouse pointer with respect to the screen.

Syntax

event.screenY

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.screenX


event.shiftKey

The shiftKey attribute retrieves a value indicating whether the SHIFT key was down when the event occurred.

Syntax

event.shiftKey

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Indicates the SHIFT key was in the down position.
false | Indicates the SHIFT key was in the up position.

See Also

  • Ambient Event Attributes


event.srcElement

The srcElement attribute retrieves the element that fired the event.

Syntax

event.srcElement

Possible Values

This attribute is a read-only object.

See Also

  • Ambient Event Attributes


event.toElement

The toElement attribute retrieves the element that the keyboard focus moved to. This attribute only applies to the onblur event; for all other events, its value is NULL.

Syntax

event.toElement

Possible Values

This attribute is a read-only object.

See Also

  • Ambient Event Attributes


event.x

The x attribute retrieves the x-coordinate of the mouse pointer with respect to the application window.

Syntax

event.x

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.y


event.y

The y attribute retrieves the y-coordinate of the mouse pointer with respect to the application window.

Syntax

event.y

Possible Values

This attribute is a read-only Number (long).

See Also

  • Ambient Event Attributes
  • event.x


BUTTON Element

The BUTTON element provides a way to create a button within a skin. The attributes below can be used to customize the behavior of a button, or a predefined button can be used for convenience.

The BUTTON element supports the following attributes.

Attribute | Description
cursor | Specifies or retrieves the cursor that appears when the mouse pointer hovers over the BUTTON.
disabledImage | Specifies or retrieves the image that displays when the BUTTON is disabled.
down | Specifies or retrieves a value indicating whether the BUTTON is in the up or down position.
downImage | Specifies or retrieves the image representing the down state of the BUTTON.
downToolTip | Specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTON and the BUTTON is in the down or depressed state.
hoverDownImage | Specifies or retrieves the image displayed when the BUTTON is in the down state and the user hovers over it with the mouse pointer.
hoverImage | Specifies or retrieves the image displayed when the BUTTON is in the up state and the user hovers over it with the mouse pointer.
image | Specifies or retrieves the default image of the BUTTON.
sticky | Specifies or retrieves a value indicating whether the BUTTON is a toggle, that is, whether it is a two-state or single-state button.
tiled | Specifies or retrieves a value indicating whether the BUTTON image will be tiled.
transparencyColor | Specifies or retrieves the color that will be transparent in the BUTTON image.
upToolTip | Specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTON and the BUTTON is in the up state.

The ambient attributes and ambient events are also supported by this element.

Predefined buttons are normal BUTTON elements with various common attribute settings specified by default. The following predefined buttons are available.

Predefined BUTTON | Description
FFWDBUTTON | A BUTTON with a built in call to player.controls.fastForward when clicked.
IMAGEBUTTON | A BUTTON used to display an image.
NEXTBUTTON | A BUTTON with a built in call to player.controls.next when clicked.
PAUSEBUTTON | A BUTTON with a built in call to player.controls.pause when clicked.
PLAYBUTTON | A BUTTON with a built in call to player.controls.play when clicked.
PREVBUTTON | A BUTTON with a built in call to player.controls.previous when clicked.
REWBUTTON | A BUTTON with a built in call to player.controls.fastReverse when clicked.
STOPBUTTON | A BUTTON with a built in call to player.controls.stop when clicked.


BUTTON.cursor

The cursor attribute specifies or retrieves the cursor that appears when the mouse pointer hovers over the BUTTON.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Default. Platform-dependent cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file)

Remarks

If the system does not recognize the cursor value specified, the cursor value remains at the previously set value.

Cursor file name paths are ignored, so the cursor file must reside in the default directory.

See Also

  • BUTTON Element


BUTTON.disabledImage

The disabledImage attribute specifies or retrieves the image that displays when the BUTTON is disabled.

Syntax

elementID.disabledImage

Possible Values

This attribute is a read/write String containing the image file name.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

This image will be displayed whenever the disabled attribute of the control is set to true. If the disabled image is larger than the defined region, the disabled image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTON Element


BUTTON.down

The down attribute specifies or retrieves a value indicating whether the BUTTON is in the up or down position.

Syntax

elementID.down

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Indicates that the BUTTON is in the down position.
false | Default. Indicates that the BUTTON is in the up position.

Remarks

In order for a BUTTON to remain in the down position, sticky must be set to true. By default, sticky is false, and any attempt to set down to true will be ignored.

If an invalid value is specified, the previous state is maintained.

See Also

  • BUTTON Element
  • BUTTON.downImage
  • BUTTON.downToolTip


BUTTON.downImage

The downImage attribute specifies or retrieves the image representing the down state of the BUTTON.

Syntax

elementID.downImage

Possible Values

This attribute is a read/write String containing the image file name.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the image attribute, or its default.

If the down image is larger than the defined region in the ambient attribute, the down image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTON Element
  • BUTTON.down
  • BUTTON.image


BUTTON.downToolTip

The downToolTip attribute specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTON and the BUTTON is in the down state.

Syntax

elementID.downToolTip

Possible Values

This attribute is a read/write String with a default value of “” (empty string) and a maximum length of 1024 characters.

See Also

  • BUTTON Element
  • BUTTON.down


BUTTON.hoverDownImage

The hoverDownImage attribute specifies or retrieves the image displayed when the BUTTON is in the down state and the user hovers over it with the mouse pointer.

Syntax

elementID.hoverDownImage

Possible Values

This attribute is a read/write String containing the image file name.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the downImage attribute, or its default.

If the hover-down image is larger than the defined region in the ambient attribute, the hover-down image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTON Element
  • BUTTON.downImage


BUTTON.hoverImage

The hoverImage attribute specifies or retrieves the image displayed when the BUTTON is in the up state and the user hovers over it with the mouse pointer.

Syntax

elementID.hoverImage

Possible Values

This attribute is a read/write String containing the image file name.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the image attribute, or its default.

If the hover image is larger than the defined region in the ambient attribute, the hover image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTON Element
  • BUTTON.image


BUTTON.image

The image attribute specifies or retrieves the default image of the BUTTON.

Syntax

elementID.image

Possible Values

This attribute is a read/write String containing the image file name.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF (including animated GIFs).

If the BUTTON image is larger than the region defined by the width and height attributes, the image will be cropped.

If the image is not specified but the height and width are, then the image directly behind this control is displayed. This can facilitate drawing the image on the VIEW itself, reducing the number of separate image files needed.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTON Element


BUTTON.sticky

The sticky attribute specifies or retrieves a value indicating whether the BUTTON is a toggle, that is, whether it is a two-state or single-state BUTTON.

Syntax

elementID.sticky

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | BUTTON is sticky.
false | Default. BUTTON is not sticky.

Remarks

If sticky is set to true, the BUTTON will change to the down state when clicked and will remain in that state until clicked again. When the BUTTON is in the down state, the down attribute will be true and the downImage will be displayed.

See Also

  • BUTTON Element
  • BUTTON.down
  • BUTTON.downImage


BUTTON.tiled

The tiled attribute specifies or retrieves a value indicating whether the BUTTON image will be tiled.

Syntax

elementID.tiled

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Image will be tiled.
false | Default. Image will not be tiled.

Remarks

If the image is smaller than the actual region of the control, then tiling the image will repeat it until it fills the entire region. If an image is not specified or cannot be retrieved, tiled will be set to false.

See Also

  • BUTTON Element
  • BUTTON.image


BUTTON.transparencyColor

The transparencyColor attribute specifies or retrieves the color that will be transparent in the BUTTON images.

Syntax

elementID.transparencyColor

Possible Values

This attribute is a read/write String with no default containing one of the following values.

Value | Description
Auto | The color of the pixel at location 0,0 in the image becomes the transparent color.
any IE color format value | An Internet Explorer color format value becomes the transparent color (for example, "red" or “#FF0000”).
None | No transparency.

Remarks

A transparent color in an image allows whatever is behind the image to show through the transparent areas. The BUTTON will still receive clicks on the transparent region.

The transparent color can be any Internet Explorer color value. If the value of the transparencyColor attribute is set to “Auto”, the color of the pixel at location 0,0 in the image is used.

If the color specified is not one of the valid IE colors, the previous value is maintained.

Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended when transparencyColor is used.

See Also

  • BUTTON Element
  • BUTTON.image
  • Color Reference


BUTTON.upToolTip

The upToolTip attribute specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTON and the BUTTON is in the up state.

Syntax

elementID.upToolTip

Possible Values

This attribute is a read/write String with a default value of “” (empty string) and a maximum length of 1024 characters.

See Also

  • BUTTON Element
  • BUTTON.down


FFWDBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.fastForward()”
upToolTip=“Fast Forward”
cursor=“system”
enabled=“wmpenabled:player.controls.fastForward”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


IMAGEBUTTON

This is a predefined BUTTON with the following default value.

cursor=“Hand”

Remarks

All buttons can contain images. This element is useful for code clarification purposes to indicate a button that is used primarily as an image container.

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


NEXTBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.next()”
upToolTip=“Next”
cursor=“system”
enabled=“wmpenabled:player.controls.next”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


PAUSEBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.pause()”
upToolTip=“Pause”
cursor=“system”
enabled=“wmpenabled:player.controls.pause”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


PLAYBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.play()”
upToolTip=“Play”
cursor=“system”
enabled=“wmpenabled:player.controls.play”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


PREVBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.previous()”
upToolTip=“Previous”
cursor=“system”
enabled=“wmpenabled:player.controls.previous”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


REWBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.fastReverse()”
upToolTip=“Fast Reverse”
cursor=“system”
enabled=“wmpenabled:player.controls.fastReverse”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


STOPBUTTON

This is a predefined BUTTON with the following default values.

onclick=“jscript:player.controls.stop()”
upToolTip=“Stop”
cursor=“system”
enabled=“wmpenabled:player.controls.stop”

Remarks

All properties of this BUTTON can be overridden by explicitly specifying them.

See Also

  • BUTTON Element


BUTTONELEMENT Element

The BUTTONELEMENT element defines a single button within a BUTTONGROUP. It supports the following attributes and predefined button elements.

This element supports the following attributes.

Attribute | Description
cursor | Specifies or retrieves the value of the BUTTONELEMENT cursor that appears when the mouse is over the BUTTONELEMENT.
down | Specifies or retrieves the up or down value of the BUTTONELEMENT.
downToolTip | Specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTONELEMENT and the BUTTONELEMENT is in the down state.
mappingColor | Specifies or retrieves the color key that identifies this BUTTONELEMENT in the BUTTONELEMENT group.
sticky | Specifies or retrieves a value indicating whether the BUTTONELEMENT is sticky. When sticky, a BUTTONELEMENT will change states after being clicked and will remain in the new state until clicked again.
upToolTip | Specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTONELEMENT and the BUTTONELEMENT is in the up or active state.

This element also supports the ambient events and the following ambient attributes: enabled, and tabStop.

The following predefined BUTTONELEMENT elements are available.

Predefined BUTTONELEMENT | Description
FFWDELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.fastForward.
NEXTELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.next.
PAUSEELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.pause.
PLAYELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.play.
PREVELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.previous.
REWELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.rewind.
STOPELEMENT | A BUTTONELEMENT with a built in onclick event handler that calls player.controls.stop.


BUTTONELEMENT.cursor

The cursor attribute specifies or retrieves the value of the BUTTONELEMENT cursor that appears when the mouse is over the BUTTONELEMENT.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Default. Platform-dependent cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

Remarks

If an invalid value is specified, the previous value is maintained.

Cursor file name paths are ignored, so the cursor file must reside in the default directory.

See Also

  • BUTTONELEMENT Element


BUTTONELEMENT.down

The down attribute specifies or retrieves a value indicating whether the button element is in the up or down position.

Syntax

elementID.down

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Indicates the BUTTONELEMENT is in the down position.
false | Default. Indicates the BUTTONELEMENT is in the up position.

Remarks

In order for a button element to remain in the down position, sticky must be set to true. By default, sticky is false, and any attempt to set down to true will be ignored.

If an invalid value is specified, the previous state is maintained.

See Also

  • BUTTONELEMENT Element
  • BUTTONELEMENT.downToolTip


BUTTONELEMENT.downToolTip

The downToolTip attribute specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTONELEMENT and the BUTTONELEMENT is in the down state.

Syntax

elementID.downToolTip

Possible Values

This attribute is a read/write String with a default value of "" (empty string) with a maximum length of 1024 characters.

See Also

  • BUTTONELEMENT Element
  • BUTTONELEMENT.down


BUTTONELEMENT.mappingColor

The mappingColor attribute specifies or retrieves the color key that identifies this BUTTONELEMENT in the BUTTONGROUP.

Syntax

elementID.mappingColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Example

The following sample is a complete skin definition file that illustrates how some of the BUTTONELEMENT attributes are used. It can be found in the Samples directory that was installed with the SDK.

<THEME>
  <VIEW
    backgroundImage = "background.bmp"
    titleBar = "False"
  >
    <PLAYER
      URL = "file:..\\media\\mellow.wma"
    />
    <EFFECTS
      id = "myeffects"
      top = "25"
      left = "88"
      width = "180"
      height = "150"
      clippingImage = "clip.png"
    />
    <BUTTONGROUP
      mappingImage = "map.bmp"
      hoverImage = "hover.bmp"
    >
      <BUTTONELEMENT
        mappingColor = "#00FF00"
        upToolTip = "Next"
        onClick = "JScript:myeffects.next();"
      />
      <BUTTONELEMENT
        mappingColor = "#FF0000"
        upToolTip = "Previous"
        onClick = "JScript:myeffects.previous();"
      />
    </BUTTONGROUP>
  </VIEW>
</THEME>

Remarks

This attribute specifies the color of the region in the button group mappingImage that corresponds to this button element. All clicks on this region are handled by this button element.

If an invalid color is specified, the BUTTONELEMENT is not activated.

See Also

  • BUTTONELEMENT Element
  • BUTTONGROUP.mappingImage
  • Color Reference


BUTTONELEMENT.sticky

The sticky attribute specifies or retrieves a value indicating whether the BUTTONELEMENT is a toggle, that is, whether it is a two-state or single-state button.

Syntax

elementID.sticky

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | BUTTONELEMENT is sticky.
false | Default. BUTTONELEMENT is not sticky.

Remarks

If the sticky attribute is set to true, the button element will change to the down state when clicked and will remain in that state until clicked again. When the button element is in the down state, the down attribute will be true and the appropriate portion of the button group downImage will be displayed.

See Also

  • BUTTONELEMENT Element
  • BUTTONELEMENT.down
  • BUTTONGROUP.downImage


BUTTONELEMENT.upToolTip

The upToolTip attribute specifies or retrieves the ToolTip text that appears when the mouse is over the BUTTONELEMENT and the BUTTONELEMENT is in the up state.

Syntax

elementID.upToolTip

Possible Values

This attribute is a read/write String with a default value of "" (empty string) with a maximum length of 1024 characters.

Example

Please see the mappingColor attribute for a sample illustrating the use of this attribute.

See Also

  • BUTTONELEMENT Element


FFWDELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.fastForward()” .
upToolTip=“Fast Forward”
cursor=“system”
enabled=“wmpenabled:player.controls.fastForward”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


NEXTELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.next()”
upToolTip=“Next”
cursor=“system”
enabled=“wmpenabled:player.controls.next”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


PAUSEELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.pause()”
upToolTip=“Pause”
cursor=“system”
enabled=“wmpenabled:player.controls.pause”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


PLAYELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.play()”
upToolTip=“Play”
cursor=“system”
enabled=“wmpenabled:player.controls.play”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


PREVELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.previous()”
upToolTip=“Previous”
cursor=“system”
enabled=“wmpenabled:player.controls.previous”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


REWELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.fastReverse()”
upToolTip=“Fast Reverse”
cursor=“system”
enabled=“wmpenabled:player.controls.fastReverse”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


STOPELEMENT

This is a predefined BUTTONELEMENT with the following default values.

onclick=“jscript:player.controls.stop()”
upToolTip=“Stop”
cursor=“system”
enabled=“wmpenabled:player.controls.stop”

Remarks

All properties of this BUTTONELEMENT can be overridden by explicitly specifying them.

See Also

  • BUTTONELEMENT Element


BUTTONGROUP Element

The BUTTONGROUP element provides a way to group several buttons within a skin. The buttons in a BUTTONGROUP are BUTTONELEMENT elements.

This element supports the following attributes.

Attribute | Description
cursor | Specifies or retrieves the type of cursor that appears when the mouse is over a button in the BUTTONGROUP.
disabledImage | Specifies or retrieves the name of the image representing the disabled state of the buttons in the BUTTONGROUP.
downImage | Specifies or retrieves the name of the image representing the down state of the BUTTONGROUP.
hoverDownImage | Specifies or retrieves the name of the image representing the hover-down state of a button in the BUTTONGROUP. The hover-down state occurs when the button is in the down state and the user hovers over it with the mouse.
hoverImage | Specifies or retrieves the name of the image representing the hover state of a button in the BUTTONGROUP. The hover state occurs when the button is in the up state and the user hovers over it with the mouse.
image | Specifies or retrieves the name of the image representing the buttons of a BUTTONGROUP.
mappingImage | Specifies or retrieves the name of the image representing the button map of the BUTTONGROUP.
radio | Specifies or retrieves a value indicating whether the BUTTONGROUP is composed of radio buttons.
showBackground | Specifies or retrieves a value indicating whether the BUTTONGROUP displays only the buttons, or displays the full bitmap specified in the image attribute.
transparencyColor | Specifies or retrieves the transparent color of the BUTTONGROUP images.

The ambient attributes and ambient events are also supported by this element.


BUTTONGROUP.cursor

The cursor attribute specifies or retrieves the type of cursor that appears when the mouse is over a button in the BUTTONGROUP.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String containing one of the following values.

Value | Description
system | Default. Platform-dependent cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

Remarks

The cursor specified applies to all buttons in the BUTTONGROUP.

If you specify an invalid cursor value, it remains at the previously set value.

Cursor file name paths are ignored, so the cursor file must reside in the default directory.

See Also

  • BUTTONGROUP Element


BUTTONGROUP.disabledImage

The disabledImage attribute specifies or retrieves the name of the image representing the disabled state of the buttons in the BUTTONGROUP.

Syntax

elementID.disabledImage

Possible Values

This attribute is a read/write String.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

When the disabled attribute of a BUTTONELEMENT element is set to true, the corresponding region of the disabledImage for the BUTTONGROUP is displayed. If the disabled image is larger than the defined region, the disabled image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTONGROUP Element


BUTTONGROUP.downImage

The downImage attribute specifies or retrieves the name of the image representing the down state of the BUTTONGROUP.

Syntax

elementID.downImage

Possible Values

This attribute is a read/write String.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the image attribute.

If the down image is larger than the defined region, the down image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTONGROUP Element
  • BUTTONGROUP.image


BUTTONGROUP.hoverDownImage

The hoverDownImage attribute specifies or retrieves the name of the image representing the hover-down state of a button in the BUTTONGROUP. The hover-down state occurs when the button is in the down state and the user hovers over it with the mouse.

Syntax

elementID.hoverDownImage

Possible Values

This attribute is a read/write String.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the downImage attribute, or its default.

If the hover-down image is larger than the defined region, the hover-down image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTONGROUP Element
  • BUTTONGROUP.downImage


BUTTONGROUP.hoverImage

The hoverImage attribute specifies or retrieves the name of the image representing the hover state of a button in the BUTTONGROUP. The hover state occurs when the button is in the up state and the user hovers over it with the mouse.

Syntax

elementID.hoverImage

Possible Values

This attribute is a read/write String.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

The default image is the one specified in the image attribute, or its default.

If the hover image is larger than the defined region, the hover image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

Example

Please see the BUTTONELEMENT.mappingColor attribute for a sample illustrating the use of this attribute.

See Also

  • BUTTONGROUP Element
  • BUTTONGROUP.image


BUTTONGROUP.image

The image attribute specifies or retrieves the name of the image representing the buttons of a BUTTONGROUP.

Syntax

elementID.image

Possible Values

This attribute is a read/write String.

Remarks

The supported image formats are BMP, JPG, PNG, and GIF.

If the image of the control is larger than the defined region, the image will be cropped.

If the image cannot be retrieved, a default image (the red-x image) is displayed.

See Also

  • BUTTONGROUP Element


BUTTONGROUP.mappingImage

The mappingImage attribute specifies or retrieves the name of the image representing the button map of the BUTTONGROUP.

Syntax

elementID.mappingImage

Possible Values

This attribute is a read/write String.

Remarks

This is a mandatory attribute that must be specified.

The mapping image should be the same dimensions as the main image. It is a map of the clickable areas of the main image. Construct the map by filling each clickable area with a different color.

When defining each BUTTONELEMENT, designate its color from the map using the mappingColor attribute. For example, if you have a stop-sign-shaped button graphic in the main image, you can create a map with the area of the sign colored red. The BUTTONELEMENT attribute must then be specified as red to make the stop-sign image clickable.

The supported image formats are BMP, JPG, PNG, and GIF (not including animated GIFs). Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended for mapping images.

Example

The following is an example of a mappingImage and the visible image it corresponds to. These images are part of the skin in the Tiny folder included with the SDK.

sample mapping image sample background image

Please see the BUTTONELEMENT.mappingColor attribute for a code sample illustrating the use of this attribute.

See Also

  • BUTTONGROUP Element
  • BUTTONELEMENT.mappingColor
  • BUTTONGROUP.image
  • BUTTONGROUP.transparencyColor


BUTTONGROUP.radio

The radio attribute specifies or retrieves a value indicating whether the BUTTONGROUP is composed of radio buttons.

Syntax

elementID.radio

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | The BUTTONGROUP is radio style.
false | Default. The BUTTONGROUP is not radio style.

Remarks

If radio is set to true, all the BUTTONELEMENT elements in the BUTTONGROUP will be sticky, but only one button at a time will be in the down state.

See Also

  • BUTTONGROUP Element
  • BUTTONELEMENT.sticky


BUTTONGROUP.showBackground

The showBackground attribute specifies or retrieves a value indicating whether the BUTTONGROUP displays only the buttons, or displays the full bitmap specified in the image attribute.

Syntax

elementID.showBackground

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Buttons are displayed and the area not occupied by buttons is drawn from the Image bitmap.
false | Default. Only the buttons are displayed.

Remarks

When showBackground is true, the entire main image will be visible.

When showBackground is false, only the areas corresponding to assigned mappingImage colors will be rendered. In other words, only BUTTONELEMENTs with their mappingColor assigned will be visible.

If an invalid value is specified, the previous state is maintained.

See Also

  • BUTTONGROUP Element
  • BUTTONELEMENT.mappingColor
  • BUTTONGROUP.image
  • BUTTONGROUP.mappingImage


BUTTONGROUP.transparencyColor

The transparencyColor attribute specifies or retrieves the transparent color of the BUTTONGROUP images.

Syntax

elementID.transparencyColor

Possible Values

This attribute is a read/write String with no default, containing one of the following values.

Value | Description
Auto | The pixel at location 0,0 in the image becomes the transparent color.
any Microsoft Internet Explorer color value | An Internet Explorer color value becomes the transparent color (for example, "red" or “#FF0000”).
None | Default. No transparency.

Remarks

A transparent color in an image will allow whatever is behind the image to show through the areas of transparency. The transparent region is clickable unless clipped by the clippingImage tag.

The color can be any Microsoft Internet Explorer color value. If the value is Auto, then the color of the pixel at location 0,0 in the image is used.

If the color specified is not one of the valid Internet Explorer colors, a warning is returned and the previous value is maintained.

Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended when transparencyColor is used.

See Also

  • BUTTONGROUP Element
  • Color Reference


CONTROLS Element

The CONTROLS element enables the following attributes of the Controls object to be specified within a skin.

Attribute | Description
currentMarker | Specifies or retrieves the current marker number.
currentPosition | Specifies or retrieves the current position of the clip in seconds from the beginning.

See Also

  • Controls Object


CUSTOMSLIDER Element

The CUSTOMSLIDER element provides a way to create and manipulate a slider control of any shape, such as a circular knob. The following tables list the attributes and event handlers supported by this element.

The CUSTOMSLIDER element supports the following attributes.

Attribute | Description
cursor | Specifies or retrieves the value of the slider control cursor that appears when the mouse is over the slider.
disabledImage | Specifies or retrieves the image of the slider used when the slider is disabled.
downImage | Specifies or retrieves the down state image of the custom slider.
hoverImage | Specifies or retrieves the image that displays when the mouse is over the custom slider.
image | Specifies or retrieves the name of the file containing the images corresponding to the various states of the custom slider.
max | Specifies or retrieves the maximum value of the range defined by the custom slider.
min | Specifies or retrieves the minimum value of the range defined by the custom slider.
positionImage | Specifies or retrieves the image map used to determine which position image from the image file to display.
toolTip | Specifies or retrieves the ToolTip text for the slider.
transparencyColor | Specifies or retrieves the transparency color of the custom slider images.
value | Specifies or retrieves the current position of the slider.

The following event handlers can be implemented in the CUSTOMSLIDER element.

Event handler | Description
onDragBegin | Handles an event that occurs when the user clicks and holds the left mouse button down and begins to drag the mouse.
onDragEnd | Handles an event that occurs when the left mouse button is released after a dragging operation.
onPositionChange | Handles an event that occurs when the position of the slider changes as a result of the user clicking or dragging.

The ambient attributes and ambient events are also supported by this element.


CUSTOMSLIDER.cursor

The cursor attribute specifies or retrieves the value of the slider control cursor that appears when the mouse is over the slider.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Platform-dependent cursor (usually an arrow).
hand | Default. Cursor is a hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

See Also

  • CUSTOMSLIDER Element


CUSTOMSLIDER.disabledImage

The disabledImage attribute specifies or retrieves the image of the slider used when the slider is disabled.

Syntax

elementID.disabledImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. If it not specified, the file specified in the image attribute will be used.

The disabledImage represents the disabled state of the CUSTOMSLIDER control. It can be a single image or a series of images representing the various states of the slider. If multiple images are used, they are arranged in the same way as the image file.

The supported image file types are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.image


CUSTOMSLIDER.downImage

The downImage attribute specifies or retrieves the down state image of the custom slider.

Syntax

elementID.downImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. If it not specified, the file specified in the image attribute will be used.

The downImage represents the down state of the CUSTOMSLIDER control. It can be a single image or a series of images representing the various states of the slider. If multiple images are used, they are arranged in the same way as the image file.

The supported image file types are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.image


CUSTOMSLIDER.hoverImage

The hoverImage attribute specifies or retrieves the image that appears when the mouse is over the custom slider.

Syntax

elementID.hoverImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. If it not specified, the file specified in the image attribute will be used.

The hoverImage represents the hover state of the CUSTOMSLIDER control; that is, the state that is shown when the mouse cursor hovers over it. It can be a single image or a series of images representing the various states of the slider. If multiple images are used, they are arranged in the same way as the image file

The supported image file types are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.image


CUSTOMSLIDER.image

The image attribute specifies or retrieves the name of the file containing the images corresponding to the various states of the custom slider.

Syntax

elementID.image

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The image attribute is required. It specifies an image file that consists of one or more sub-images, arranged either horizontally or vertically, representing the various states of the custom slider. Each sub-image must have the same dimensions as the positionImage or the custom slider will not work correctly. The height or width of the overall image must therefore be an even multiple of the height or width of the positionImage.

The supported image file types are BMP, JPG, PNG, and GIF (not including animated GIFs).

Example

The following is an example of a custom slider image. The corresponding positionImage is shown in the example section of the positionImage property.

sample CUSTOMSLIDER image

The positionImage attribute also contains a code sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.positionImage


CUSTOMSLIDER.max

The max attribute specifies or retrieves the maximum value of the range defined by the custom slider.

Syntax

elementID.max

Possible Values

This attribute is a read/write Number (float) with a default value of 100.

Remarks

The value of max must be greater than that of min.

Example

Please see the positionImage attribute for a sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.min


CUSTOMSLIDER.min

The min attribute specifies or retrieves the minimum value of the range defined by the custom slider.

Syntax

elementID.min

Possible Values

This attribute is a read/write Number (float) with a default value of zero.

Remarks

The value of min must be less than max.

Example

Please see the positionImage attribute for a sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.max


CUSTOMSLIDER.onDragBegin

The onDragBegin event handler handles an event that occurs when the user clicks and holds the left mouse button down and begins to drag the mouse.

Syntax

onDragBegin

See Also

  • CUSTOMSLIDER Element


CUSTOMSLIDER.onDragEnd

The onDragEnd event handler handles an event that occurs when the left mouse button is released after a dragging operation.

Syntax

onDragEnd

See Also

  • CUSTOMSLIDER Element


CUSTOMSLIDER.onPositionChange

The onPositionChange event handler handles an event that occurs when the position of the slider changes as a result of the user clicking or dragging.

Syntax

onPositionChange

Remarks

If the position of the custom slider changes as a result of the value attribute being modified in script, this event is not fired. To accommodate this possibility, implement the value_onchange event handler instead.

See Also

  • CUSTOMSLIDER Element


CUSTOMSLIDER.positionImage

The positionImage attribute specifies or retrieves the image map used to determine which position image from the image file to display.

Syntax

elementID.positionImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is required and must be specified.

The positionImage is not displayed. Instead, it serves as a map defining the clickable regions of the displayed image. The displayed image is one of the sub-images of the image file and represents the actual state of the slider. The positionImage includes a number of gray scale regions equal to the number of these sub-images. The sub-images must have the same dimensions as the positionImage or the custom slider will not work correctly.

Any region that is not in gray scale will not be clickable. The clickable regions should be set to colors that range evenly across the gray scale spectrum from black to white. The red, green, and blue color values should all be equal to achieve true gray scale, and should be incremented in successive regions by a value equal to 255 divided by the total number of regions minus one, rounding to the nearest whole number. For example, if there are ten regions, the increment would be 51 (255 divided by 5), and the six gray scale values would be 0, 51, 102, 153, 204, and 255. The hexadecimal color values for the six regions would then be #000000, #333333, #666666, #999999, #CCCCCC, and #FFFFFF.

In this way, the regions will have a sequence dictated by their gray scale color values, and this sequence will correspond to the sequence of sub-images in the image file. When one of the regions is clicked, the corresponding sub-image is shown and the value of the custom slider is updated accordingly.

The supported image file types are BMP, JPG, PNG, and GIF (not including animated GIFs).

Example

The following is an example of a custom slider positionImage. The corresponding image is shown in the example section of the image property.

sample positionImage graphic

The following code illustrates the use of CUSTOMSLIDER attributes.

<THEME>
  <VIEW
    backgroundImage = "background.bmp"
    titleBar = "False"
  >

    <PLAYER
      URL = "file:..\\media\\mellow.wma"
    >
      <CONTROLS
        currentPosition_onchange = "myslider.value = player.controls.currentPosition;"
      />
    </PLAYER>

    <SLIDER
      id = "myslider"
      min = "0"
      max = "wmpprop:player.currentMedia.duration"
      onmouseup = "player.controls.currentPosition = myslider.value; "
      tooltip = "current position"
      height = "10"
      width = "180"
      top = "150"
      left = "88"
      backgroundColor = "red"
      foregroundColor = "blue"
      thumbImage = "thumb.bmp"
    />

    CUSTOMSLIDER
      top = "120"
      left = "23"
      min = "0"
      max = "100"
      borderSize = "10"
      toolTip = "volume control"
      image = "dial.bmp"
      transparencyColor = "#00FFFF"
      positionImage = "dialmap.bmp"
      enabled = "true"
      value = "wmpprop:player.settings.volume"
      value_onchange = "player.settings.volume = value"
    />

    <EFFECTS
      id = "myeffects"
      top = "25"
      left = "88"
      width = "180"
      height = "100"
    />

    <BUTTONGROUP
      mappingImage = "map.bmp"
      hoverImage = "hover.bmp"
    >

      <BUTTONELEMENT
        mappingColor = "#00FF00"
        upToolTip = "Next"
        onClick = "JScript:myeffects.next();"
      />

      <BUTTONELEMENT
        mappingColor = "#FF0000"
        upToolTip = "Previous"
        onClick = "JScript:myeffects.previous();"
      />

    </BUTTONGROUP>

  </VIEW>
</THEME>

See Also

  • CUSTOMSLIDER Element
  • CUSTOMSLIDER.image


CUSTOMSLIDER.toolTip

The toolTip attribute specifies or retrieves the ToolTip text for the slider.

Syntax

elementID.toolTip

Possible Values

This attribute is a read/write String with a maximum length of 1024 characters. It has no default value.

Remarks

If no ToolTip is defined, then the there is no ToolTip for the CUSTOMSLIDER.

Example

Please see the positionImage attribute for a sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element


CUSTOMSLIDER.transparencyColor

The transparencyColor attribute specifies or retrieves the transparency color of the custom slider images.

Syntax

elementID.transparencyColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

Any part of the custom slider images containing the transparencyColor will allow the background to show through.

Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended when transparencyColor is used.

Example

Please see the positionImage attribute for a sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element
  • Color Reference


CUSTOMSLIDER.value

The value attribute specifies or retrieves the current position of the slider.

Syntax

elementID.value

Possible Values

This attribute is a read/write Number (float) with a default value equal to the min attribute.

Remarks

The value must be greater than or equal to min and less than or equal to max. If the value falls outside the range, a warning is issued, and the value does not change.

Example

Please see the positionImage attribute for a sample illustrating how the attributes of the CUSTOMSLIDER element are used.

See Also

  • CUSTOMSLIDER Element


EFFECTS Element

The EFFECTS element provides a way to organize and manipulate visualizations, using the following attributes and methods.

The EFFECTS element supports the following attributes.

Attribute | Description
allowAll | Specifies or retrieves a value indicating whether to include all the visualizations in the registry.
currentEffect | Specifies or retrieves the current visualization.
currentEffectPresetCount | Retrieves number of available presets for the current visualization.
currentEffectTitle | Retrieves the display title of the current visualization.
currentEffectType | Retrieves the registry name of the current visualization.
currentPreset | Specifies or retrieves the current preset of the current visualization.
currentPresetTitle | Retrieves the title of the current preset of the current visualization.
effectCanGoFullScreen | Retrieves a value indicating whether the current visualization can be displayed full-screen.
effectHasPropertyPage | Retrieves a value indicating whether the current visualization has a property page.
fullScreen | Specifies or retrieves a value indicating whether the current visualization is displayed full-screen. Can only be set at run time.
windowed | Specifies or retrieves a value indicating whether the visualization will be windowed or windowless, that is, whether the entire rectangle of the control will be visible at all times, or whether it can be clipped. Can only be set at design time.

The EFFECTS element supports the following methods.

Method | Description
next | Displays the next visualization preset, moving to the next visualization if necessary.
nextEffect | Displays the first preset of the next visualization, skipping intervening presets.
nextPreset | Displays the next preset of the current visualization.
previous | Displays the previous visualization preset, moving to the last preset of the previous visualization if necessary.
previousEffect | Displays the previous visualization, skipping presets.
previousPreset | Displays the previous preset of the current visualization.
settings | Displays the attribute page for the current visualization, if present.

The ambient attributes and ambient events are also supported by this element, except where noted.


EFFECTS.allowAll

The allowAll attribute specifies or retrieves a value indicating whether to include all the visualizations that are in the registry.

Syntax

elementID.allowAll

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. Allows cycling of all visualizations on the user’s system.
false | Limits cycling to visualizations appearing within EFFECTS tags.

Remarks

If this attribute is set to false, only the visualizations appearing within EFFECTS tags can be cycled through using previous/next. If it is set to true, then all visualizations that are registered on the user’s system can be cycled through. If it is set to true and you specify any visualizations within EFFECTS tags, then the attributes specified in these tags are applied to all visualizations on the user’s system.

See Also

  • EFFECTS Element


EFFECTS.currentEffect

The currentEffect attribute specifies or retrieves the current visualization.

Syntax

elementID.currentEffect

Possible Values

This attribute is a read/write object. The default value is the first visualization in the authoring order. If there are no visualizations authored in the skin, the default is the first visualization in the registry.

See Also

  • EFFECTS Element
  • EFFECTS.currentEffectTitle
  • EFFECTS.currentEffectType


EFFECTS.currentEffectPresetCount

The currentEffectPresetCount attribute retrieves number of available presets for the current visualization.

Syntax

elementID.currentEffectPresetCount

Possible Values

This attribute is a read-only Number (long).

See Also

  • EFFECTS Element


EFFECTS.currentEffectTitle

The currentEffectTitle attribute retrieves the display title of the current visualization.

Syntax

elementID.currentEffectTitle

Possible Values

This attribute is a read-only String.

See Also

  • EFFECTS Element
  • EFFECTS.currentEffect


EFFECTS.currentEffectType

The currentEffectType attribute retrieves the registry name of the current visualization.

Syntax

elementID.currentEffectType

Possible Values

This attribute is a read-only String.

See Also

  • EFFECTS Element
  • EFFECTS.currentEffect


EFFECTS.currentPreset

The currentPreset attribute specifies or retrieves the current preset of the current visualization.

Syntax

elementID.currentPreset

Possible Values

This attribute is a read/write Number (long) indicating the index of the preset. The indexes begin with zero, which is also the default value.

See Also

  • EFFECTS Element


EFFECTS.currentPresetTitle

The currentPresetTitle attribute retrieves the title of the current preset of the current visualization.

Syntax

elementID.currentPresetTitle

Possible Values

This attribute is a read-only String.

See Also

  • EFFECTS Element


EFFECTS.effectCanGoFullScreen

The effectCanGoFullScreen attribute retrieves a value indicating whether the current visualization can be displayed full-screen.

Syntax

elementID.effectCanGoFullScreen

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Visualization can be displayed full-screen.
false | Visualization cannot be displayed full-screen.

See Also

  • EFFECTS Element


EFFECTS.effectHasPropertyPage

The effectHasPropertyPage attribute retrieves a value indicating whether the current visualization has a property page.

Syntax

elementID.effectHasPropertyPage

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Visualization has a property page.
false | Visualization does not have a property page.

See Also

  • EFFECTS Element


EFFECTS.fullScreen

The fullScreen attribute specifies or retrieves a value indicating whether the current visualization is displayed full-screen. This attribute can only be set at run time.

Syntax

elementID.fullScreen

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Visualization is displayed full-screen.
false | Default. Visualization is not displayed full-screen.

Remarks

A visualization can be put into full-screen mode only while media is playing or paused. If Player.currentMedia is video, a video plug-in must be present. If it is audio, a visualization plug-in that supports full-screen display must be present.

See Also

  • EFFECTS Element


EFFECTS.next

The next method displays the next visualization preset, moving to the next visualization if necessary.

Syntax

elementID.next()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the current preset is the last one in the series of all available visualizations, the first preset of the first visualization is made current.

See Also

  • EFFECTS Element
  • EFFECTS.allowAll
  • EFFECTS.previous


EFFECTS.nextEffect

The nextEffect method displays the first preset of the next visualization, skipping intervening presets.

Syntax

elementID.nextEffect()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

This method displays the first preset of the next visualization in the authoring order. If the current visualization is the last in the authoring order, and if allowAll is false, the first visualization is made current.

See Also

  • EFFECTS Element
  • EFFECTS.allowAll
  • EFFECTS.previousEffect


EFFECTS.nextPreset

The nextPreset method displays the next preset of the current visualization.

Syntax

elementID.nextPreset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the current preset is the last one in the list for the current visualization, the first preset is made current.

See Also

  • EFFECTS Element
  • EFFECTS.allowAll
  • EFFECTS.previous


EFFECTS.previous

The previous method displays the previous visualization preset, moving to the last preset of the previous visualization if necessary.

Syntax

elementID.previous()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the current preset is the first one in the series of all available visualizations, the last preset of the last visualization is made current.

See Also

  • 11EFFECTS Element
  • EFFECTS.next
  • EFFECTS.allowAll


EFFECTS.previousEffect

The previousEffect method displays the previous visualization, skipping presets.

Syntax

elementID.previousEffect()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

This method displays the previous visualization in the authoring order. If the current visualization is the first in the authoring order, and if allowAll is false, the last visualization is made current.

See Also

  • EFFECTS Element
  • EFFECTS.nextEffect
  • EFFECTS.allowAll


EFFECTS.previousPreset

The previousPreset method displays the previous preset of the current visualization.

Syntax

elementID.previousPreset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the current preset is the first one in the list for the current visualization, the last preset is made current.

See Also

  • EFFECTS Element
  • EFFECTS.allowAll
  • EFFECTS.previous


EFFECTS.settings

The settings method displays the attribute page for the current visualization, if present.

Syntax

elementID.settings()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • EFFECTS Element


EFFECTS.windowed

The windowed attribute specifies or retrieves a value indicating whether the visualization will be windowed or windowless, that is, whether the entire rectangle of the control will be visible at all times, or whether it can be clipped. This attribute can only be set at design time.

Syntax

elementID.windowed

Possible Values

This attribute is a Boolean specified at design time and read-only thereafter.

Value | Description
true | The control will be windowed.
false | Default. The control will be windowless.

Remarks

If a non-rectangular visualization window is desired, or if any part of the window is covered by an image, this attribute must be set to false. This sacrifices some performance to do the necessary clipping.

If windowed is set to true, any image covering the visualization window is ignored, and the visualization window has the highest-level z-order.

See Also

  • EFFECTS Element


EQUALIZERSETTINGS Element

The EQUALIZERSETTINGS element provides a way to manipulate the graphic equalizer settings of Windows Media Player using the attributes and method listed here.

The EQUALIZERSETTINGS element supports the following attributes.

Attribute | Description
bands | Retrieves the number of frequency bands supported.
bypass | Specifies or retrieves a value indicating whether the equalizer filter is bypassed in the filter graph.
currentPreset | Specifies or retrieves the index of the current preset.
currentPresetTitle | Retrieves the title of the current preset.
gainLevels | Specifies or retrieves the gain level of the band corresponding to the index provided.
gainLevel1 | Specifies or retrieves the gain level of band 1.
gainLevel2 | Specifies or retrieves the gain level of band 2.
gainLevel3 | Specifies or retrieves the gain level of band 3.
gainLevel4 | Specifies or retrieves the gain level of band 4.
gainLevel5 | Specifies or retrieves the gain level of band 5.
gainLevel6 | Specifies or retrieves the gain level of band 6.
gainLevel7 | Specifies or retrieves the gain level of band 7.
gainLevel8 | Specifies or retrieves the gain level of band 8.
gainLevel9 | Specifies or retrieves the gain level of band 9.
gainLevel10 | Specifies or retrieves the gain level of band 10.
presetCount | Retrieves the number of presets available.

The EQUALIZERSETTINGS element supports the following methods.

Method | Description
nextPreset | Applies the next equalizer preset.
previousPreset | Applies the previous equalizer preset.
reset | Resets the gain levels of all bands to zero decibels.

This element can implement the onchange event handlers.


EQUALIZERSETTINGS.bands

The bands attribute retrieves the number of frequency bands supported.

Syntax

elementID.bands

Possible Values

This attribute is a read-only Number (long).

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.bypass

The bypass attribute specifies or retrieves a value indicating whether the equalizer filter is bypassed in the filter graph.

Syntax

elementID.bypass

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. The equalizer filter is bypassed.
false | The equalizer filter is used.

Remarks

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.currentPreset

The currentPreset attribute specifies or retrieves the index of the current preset.

Syntax

elementID.currentPreset

Possible Values

This attribute is a read/write Number (long).

Remarks

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.currentPresetTitle

The currentPresetTitle attribute retrieves the title of the current preset.

Syntax

elementID.currentPresetTitle

Possible Values

This attribute is a read-only String.

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.gainLevels

The gainLevels attribute specifies or retrieves the gain level of the band corresponding to the index provided.

Syntax

elementID.gainLevels(theBand)

Parameters

theBand

Number (long) between 1 and 10 indicating the index of the band.

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20.

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.gainLevel1

The gainLevel1 attribute specifies or retrieves the gain level of band 1.

Syntax

elementID.gainLevel1

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 31Hz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel2

The gainLevel2 attribute specifies or retrieves the gain level of band 2.

Syntax

elementID.gainLevel2

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 62Hz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel3

The gainLevel3 attribute specifies or retrieves the gain level of band 3.

Syntax

elementID.gainLevel3

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 125Hz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel4

The gainLevel4 attribute specifies or retrieves the gain level of band 4.

Syntax

elementID.gainLevel4

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 250Hz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel5

The gainLevel5 attribute specifies or retrieves the gain level of band 5.

Syntax

elementID.gainLevel5

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 500Hz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel6

The gainLevel6 attribute specifies or retrieves the gain level of band 6. It has a default value of zero.

Syntax

elementID.gainLevel6

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 1kHz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel7

The gainLevel7 attribute specifies or retrieves the gain level of band 7.

Syntax

elementID.gainLevel7

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 2kHz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel8

The gainLevel8 attribute specifies or retrieves the gain level of band 8.

Syntax

elementID.gainLevel8

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 4kHz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel9

The gainLevel9 attribute specifies or retrieves the gain level of band 9.

Syntax

elementID.gainLevel9

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 8kHz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.gainLevel10

The gainLevel10 attribute specifies or retrieves the gain level of band 10.

Syntax

elementID.gainLevel10

Possible Values

This attribute is a read/write Number (float) with a value normally ranging from –20 to +20. It has a default value of zero.

Remarks

This attribute adjusts the portion of the audio frequency spectrum centered on 16kHz.

If this attribute is not specified, the previous value will be retained.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.gainLevels


EQUALIZERSETTINGS.nextPreset

The nextPreset method applies the next equalizer preset.

Syntax

elementID.nextPreset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Example

<SUBVIEW id=”eqtray”>
  <EQUALIZERSETTINGS id=”eq”/>
  <BUTTON
    id="nextPreset"
    onClick="eq.nextPreset();"
  />
  <BUTTON
    id="prevPreset"
    onClick="eq.previousPreset();"
  />
  <TEXT
    id="currentPreset"
    value="wmpprop:eq.currentPresetTitle"
  />
</SUBVIEW>

Remarks

If the current preset is the last one available, the first preset is made current.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.previousPreset


EQUALIZERSETTINGS.presetCount

The presetCount attribute retrieves the number of presets available.

Syntax

elementID.presetCount

Possible Values

This attribute is a read-only Number (long).

See Also

  • EQUALIZERSETTINGS Element


EQUALIZERSETTINGS.previousPreset

The previousPreset method applies the previous equalizer preset.

Syntax

elementID.previousPreset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If the current preset is the first one available, the last preset is made current.

See Also

  • EQUALIZERSETTINGS Element
  • EQUALIZERSETTINGS.nextPreset


EQUALIZERSETTINGS.reset

The reset method resets the gain levels of all bands to zero decibels.

Syntax

elementID.reset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • EQUALIZERSETTINGS Element


PLAYER Element

The PLAYER element enables the following attribute of the Player object to be specified within a skin definition file.

Attribute | Description
url | Specifies or retrieves the name of the file to play.

The PLAYER element can implement event handlers for the following events fired from the Player object.

Event | Description
buffering | Occurs when the player begins or ends buffering.
currentitemchange | Occurs when the current item changes.
currentplaylistchange | Occurs when the current playlist changes.
error | Occurs when the player encounters an error condition.
markerhit | Occurs when the player encounters a marker in the clip.
mediachange | Occurs when a media item changes.
mediacollectionchange | Occurs when the MediaCollection object changes.
modechange | Occurs when switching between shuffle and normal mode.
openstatechange | Occurs when player.openState changes.
playlistchange | Occurs when a playlist changes.
playstatechange | Occurs when player.playState changes.
positionchange | Occurs when player.controls.currentPosition changes.
scriptcommand | Occurs when the player encounters a script command embedded in the Windows Media file.
statuschange | Occurs when the status property changes value.

See Also

  • Player Object


PLAYLIST Element

The PLAYLIST element provides a way to organize media items in a list for easy manipulation using the attributes and methods shown here.

The PLAYLIST element supports the following attributes.

Attribute | Description
allowColumnSorting | Specifies or retrieves a value indicating whether sorting on column headers is allowed.
allowItemEditing | Specifies or retrieves a value indicating whether items in a playlist support in-place editing.
backgroundColor | Specifies or retrieves the background color.
backgroundImage | Specifies or retrieves the background image.
checkboxesVisible | Specifies or retrieves a value indicating whether checkboxes are visible.
columnCount | Retrieves the number of columns shown.
columnOrder | Specifies or retrieves the order of the playlist columns.
columns | Defines the columns that appear in the Playlist control.
columnsVisible | Specifies or retrieves a value indicating whether columns are shown.
copying | Retrieves a value indicating whether the Playlist control is in the act of copying.
disabledItemColor | Specifies or retrieves the color of a disabled CD track or of online content when offline.
dropDownList | Specifies or retrieves a value indicating which elements show up in the drop-down list for a given instance of the Playlist control.
dropDownToolTip | Specifies or retrieves the ToolTip shown when the user hovers over the Playlist control drop-down menu.
dropDownVisible | Specifies or retrieves a value indicating whether the Playlist drop-down selector is visible.
foregroundColor | Specifies or retrieves the foreground color.
itemPlayingBackgroundColor | Specifies or retrieves the background color of the currently playing Playlist item.
itemPlayingColor | Specifies or retrieves the highlight color that indicates the currently playing item in the playlist.
playlist | Specifies or retrieves the Playlist object that the Playlist control provides an interface to.
playlistItemsVisible | Specifies or retrieves a value indicating whether items in the playlist are visible.

The PLAYLIST element supports the following methods.

Method | Description
abortCopy | Cancels a copy operation.
addSelectedToPlaylist | Adds the selected item to the playlist.
copy | Begins a copy operation from the CD.
deleteSelected | Deletes the selected item from the playlist.
deleteSelectedFromLibrary | Deletes the selected item from the playlist and from the media library.
getNextCheckedItem | Retrieves the index of the next checked item in the playlist following the specified index.
getNextSelectedItem | Retrieves the index of the next selected item in the playlist following the specified index.
moveSelectedDown | Moves the selected item down one position in the list.
moveSelectedUp | Moves the selected item up one position in the list.
setCheckedState | Specifies that the indexed item in the playlist is checked.
setColumnResizeMode | Specifies how the indexed column sizes itself.
setColumnWidth | Specifies the column width and changes the resize mode of the column to “wmpcrmFixed”.
setSelectedState | Specifies that the indexed item in the playlist is selected.
sortColumn | Sorts the data in the specified column.

The ambient attributes and ambient events are also supported by this element, except where noted.


PLAYLIST.abortCopy

The abortCopy method cancels a copy operation.

Syntax

elementID.abortCopy()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element


PLAYLIST.addSelectedToPlaylist

The addSelectedToPlaylist method adds the selected item to a playlist.

Syntax

elementID.addSelectedToPlaylist(playlist)

Parameters

playlist

Playlist object that will receive the selected item.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element


PLAYLIST.allowColumnSorting

The allowColumnSorting attribute specifies or retrieves a value indicating whether sorting column contents is allowed.

Syntax

elementID.allowColumnSorting

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. Sorting column contents is allowed.
false | Sorting column contents is not allowed.

See Also

  • PLAYLIST Element


PLAYLIST.allowItemEditing

The allowItemEditing attribute specifies or retrieves a value indicating whether items in a playlist will support in-place editing.

Syntax

elementID.allowItemEditing

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. In-place editing is allowed.
false | In-place editing is not allowed.

See Also

  • PLAYLIST Element


PLAYLIST.backgroundColor

The backgroundColor attribute specifies or retrieves the background color.

Syntax

elementID.backgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has a default value equal to the Windows system window color.

See Also

  • PLAYLIST Element
  • Color Reference


PLAYLIST.backgroundImage

The backgroundImage attribute specifies or retrieves the background image.

Syntax

elementID.backgroundImage

Possible Values

This attribute is a read/write String containing the name of an image file. It has no default value.

Remarks

If the image height and width are smaller than the height and width of the Playlist control, the image is tiled. The supported formats are BMP, JPG, GIF and PNG.

See Also

  • PLAYLIST Element


PLAYLIST.checkboxesVisible

The checkboxesVisible attribute specifies or retrieves a value indicating whether check boxes are visible.

Syntax

elementID.checkboxesVisible

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Check boxes are visible.
false | Default. Check boxes are not visible.

Remarks

Check boxes appear in the far left column.

See Also

  • PLAYLIST Element


PLAYLIST.columnCount

The columnCount attribute retrieves the number of columns shown.

Syntax

elementID.columnCount

Possible Values

This attribute is a read-only Number (long).

See Also

  • PLAYLIST Element


PLAYLIST.columnOrder

The columnOrder attribute specifies or retrieves the order of the playlist columns.

Syntax

elementID.columnOrder

Possible Values

This attribute is a read/write String specifying a semicolon-delimited list of Playlist column indexes. The default value is “0;1;2;3”.

See Also

  • PLAYLIST Element


PLAYLIST.columns

The columns attribute defines the columns that appear in the Playlist control.

Syntax

elementID.columns

Possible Values

This attribute is a read/write String in the following format:

DB_NAME=FRIENDLY_NAME;DB_NAME=FRIENDLY_NAME; etc…

where FRIENDLY_NAME is the value shown in the column header of the Playlist control, and DB_NAME is a value from the following table. Note that a Playlist item might be a media item from the media library or from a CD, or it might be another Playlist that is either user-created or taken from a CD. Some columns are valid only with certain Playlist items as indicated in the Description column.

Value | Description
Album | The name of the album. Used with media items only.
Artist | The name of the artist. Not used with user-created Playlists.
Author | The name of the artist.
Bitrate | The bit rate of the content. Used only with media items from the media library.
CDTrackEnabled | Indicates whether the CD track is enabled. Used only with CD media items.
Checked | Reserved for future use.
Copyright | The copyright of the Playlist item. Not used with CD playlists or media items.
CreationDate | The date and time that the entry in the media library was created. Used only with items from the media library.
DigitallySecure | Indicates whether the item is protected with Windows Media Rights Manager. Used only with media items from the media library.
Duration | The duration of the media item.
FileType | Reserved for future use.
Genre | The genre of the Playlist item. Not used with playlists from CDs.
MediaAttribute | Reserved for future use.
MediaType | The type of the media item (audio or video).
MetadataSource | The source of the metadata for this CD track (AMG, WindowsMedia.com, etc.). Used only with CD media items.
ModifiedBy | Reserved for future use.
Name | The name of the Playlist item.
OriginalIndex | If applicable, the corresponding CD track identifier. Used only with CD media items.
PlayCount | The number of times the content has been played through to the end. Used only with media items from the media library.
PlaylistAttribute | Reserved for future use.
Rating | Reserved for future use.
SourceURL | The path or URL to the content. Used only with media items from the media library.
Status | The copying status of a CD track being copied. Used only with CD media items.
Style | Reserved for future use.
TOC | If applicable, the corresponding CD Table of Contents Indentifier. Not used with user-created Playlists.

Remarks

If one of the columns does not exist in the database, it is left blank.

A maximum of 31 columns may be specified.

If you specify a duplicate column, the data in the first column will be left-aligned but all other duplicate columns will be right-aligned. For example, if you have two duration columns, the data will be left-aligned in the first and right-aligned in the second.

See Also

  • PLAYLIST Element
  • PLAYLIST.columnsVisible


PLAYLIST.columnsVisible

The columnsVisible attribute specifies or retrieves a value indicating whether column headers are shown.

Syntax

elementID.columnsVisible

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. Column headers are shown.
false | Column headers are not shown.

See Also

  • PLAYLIST Element
  • PLAYLIST.columns


PLAYLIST.copy

The copy method begins a copy operation from the CD.

Syntax

elementID.copy()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

Only the items that are checked within the playlist are copied.

See Also

  • PLAYLIST Element
  • PLAYLIST.copying


PLAYLIST.copying

The copying attribute retrieves a value indicating whether the Playlist control is in the act of copying.

Syntax

elementID.copying

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | The Playlist control is in the act of copying.
false | Default. The Playlist control is not in the act of copying.

See Also

  • PLAYLIST Element
  • PLAYLIST.copy


PLAYLIST.deleteSelected

The deleteSelected method deletes the selected item from the playlist.

Syntax

elementID.deleteSelected()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element
  • PLAYLIST.deleteSelectedFromLibrary


PLAYLIST.deleteSelectedFromLibrary

The deleteSelectedFromLibrary method deletes the selected item from the playlist and from the media library.

Syntax

elementID.deleteSelectedFromLibrary()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element
  • PLAYLIST.deleteSelected


PLAYLIST.disabledItemColor

The disabledItemColor attribute specifies or retrieves the color of a disabled CD track or of online content when offline.

Syntax

elementID.disabledItemColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has a default value of “gray”.

See Also

  • PLAYLIST Element
  • Color Reference


PLAYLIST.dropDownList

The dropDownList attribute specifies or retrieves a value indicating which elements show up in the drop-down list box for a given instance of the Playlist control.

Syntax

elementID.dropDownList

Possible Values

This attribute is a read/write String containing one of the following values.

Value | Description
showAlbums | Shows albums.
showAll | Default. Shows all available elements including CD playlists, user playlists, and radio presets.
showCD | Shows the CD playlist.
showCurrent | Shows the current, unsaved playlist.
showLibrary | Shows only library playlists.
showRadio | Shows radio presets.
showQueries | Shows queries.

See Also

  • PLAYLIST Element


PLAYLIST.dropDownToolTip

The dropDownToolTip attribute specifies or retrieves the ToolTip shown when the user hovers over the Playlist control dropdown menu.

Syntax

elementID.dropDownToolTip

Possible Values

This attribute is a read/write String with a default value of “Choose Playlist or Music”.

See Also

  • PLAYLIST Element


PLAYLIST.dropDownVisible

The dropDownVisible attribute specifies or retrieves a value indicating whether the Playlist dropdown selector is visible.

Syntax

elementID.dropDownVisible

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. The dropdown is visible.
false | The dropdown is not visible.

See Also

  • PLAYLIST Element


PLAYLIST.foregroundColor

The foregroundColor attribute specifies or retrieves the foreground color.

Syntax

elementID.foregroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has a default value equal to the Windows system text color.

See Also

  • PLAYLIST Element
  • Color Reference


PLAYLIST.getNextCheckedItem

The getNextCheckedItem method retrieves the index of the next checked item in the playlist following the specified index.

Syntax

elementID.getNextCheckedItem(item)

Parameters

item

Number (long) indicating the index of the item to search after.

Return Values

This method returns a Number (long).

Remarks

When there are no further checked items, this method returns –1.

See Also

  • PLAYLIST Element


PLAYLIST.getNextSelectedItem

The getNextSelectedItem method retrieves the index of the next selected item in the playlist following the specified index.

Syntax

elementID.getNextSelectedItem(item)

Parameters

item

Number (long) indicating the index of the item to search after.

Return Values

This method returns a Number (long).

Remarks

When there are no further selected items, this method returns –1.

See Also

  • PLAYLIST Element


PLAYLIST.itemPlayingBackgroundColor

The itemPlayingBackgroundColor attribute specifies or retrieves the background color of the currently playing playlist item.

Syntax

elementID.itemPlayingBackgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has a default value of “#222222”.

See Also

  • PLAYLIST Element
  • Color Reference


PLAYLIST.itemPlayingColor

The itemPlayingColor attribute specifies or retrieves the highlight color that indicates the currently playing item in the playlist.

Syntax

elementID.itemPlayingColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has a default value of “#00FF00”.

See Also

  • PLAYLIST Element
  • Color Reference


PLAYLIST.moveSelectedDown

The moveSelectedDown method moves the selected item down one position in the list.

Syntax

elementID.moveSelectedDown()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element
  • PLAYLIST.moveSelectedUp


PLAYLIST.moveSelectedUp

The moveSelectedUp method moves the selected item up one position in the list.

Syntax

elementID.moveSelectedUp()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element
  • PLAYLIST.moveSelectedDown


PLAYLIST.playlist

The playlist attribute specifies or retrieves the Playlist object that the Playlist control provides an interface to.

Syntax

elementID.playlist

Possible Values

This attribute is a read/write Playlist object with no default value.

Remarks

If the playlist specified is invalid or if no value is specified, the Playlist control displays the currently playing Media item.

See Also

  • PLAYLIST Element
  • Playlist Object


PLAYLIST.playlistItemsVisible

The playlistItemsVisible attribute specifies or retrieves a value indicating whether the Playlist items area is visible.

Syntax

elementID.playlistItemsVisible

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. Playlist items area is visible.
false | Playlist items area is not visible.

Remarks

The Playlist items area includes the column headers, the contents of the columns, and the scrollbars (if present).

See Also

  • PLAYLIST Element


PLAYLIST.setCheckedState

The setCheckedState method specifies that the indexed item in the playlist is selected.

Syntax

elementID.setCheckedState(item)

Parameters

item

Number (long) indicating the index of the playlist item to be selected.

Return Values

This method returns a Boolean.

Remarks

You can set all items to the checked state by specifying –1 in the item parameter.

See Also

  • PLAYLIST Element


PLAYLIST.setColumnResizeMode

The setColumnResizeMode method specifies how the indexed column sizes itself.

Syntax

elementID.setColumnResizeMode(column, mode)

Parameters

column

Number (long) indicating the index of the column to be changed.

mode

String indicating the sizing mode. Contains one of the following values.

String | Description
AutosizeHeader | The column resizes to accommodate all data in both the column and the header.
AutosizeData | The column resizes to accommodate all data in the column only.
Fixed | The column is a fixed size.
Stretches | The column resizes to use the remaining space in the Playlist control after all other columns are resized.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element


PLAYLIST.setColumnWidth

The setColumnWidth method specifies the column width and changes the resize mode of the column to “Fixed”.

Syntax

elementID.setColumnWidth(column, width)

Parameters

column

Number (long) indicating the index of the column being changed.

width

Number (long) indicating the new width in pixels.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element
  • PLAYLIST.setColumnResizeMode


PLAYLIST.setSelectedState

The setSelectedState method specifies that the indexed item in the playlist is selected.

Syntax

elementID.setSelectedState(item)

Parameters

item

Number (long) indicating the index of an item in the playlist.

Return Values

This method does not return a value.

Remarks

You can set all items to the selected state by specifying –1 in the item parameter.

See Also

  • PLAYLIST Element


PLAYLIST.sortColumn

The sortColumn method sorts the data in the specified column.

Syntax

elementID.sortColumn(column)

Parameters

column

Number (long) indicating the index of the column to sort.

Return Values

This method does not return a value.

See Also

  • PLAYLIST Element


PROGRESSBAR Element

The PROGRESSBAR element provides a way to display progress information in a horizontal or vertical control. This element is identical to the SLIDER element. A progress bar is normally a slider that is not interactive, but there is nothing that prevents it from being used interactively. This element is provided solely as a convenience tag for making the noninteractivity clear in your code, if you choose to use it that way. It has no other value.


SETTINGS Element

The SETTINGS element enables the following attributes of the Settings object to be specified within a skin.

Attribute | Description
autoStart | Specifies or retrieves a value indicating whether the current media item begins playing automatically.
balance | Specifies or retrieves the current stereo balance.
baseURL | Specifies or retrieves the base URL used for relative path resolution.
defaultFrame | Specifies or retrieves the name of the frame used to display a URL received in a scriptCommand.
enableErrorDialogs | Specifies or retrieves a value indicating whether error dialogs are shown automatically.
invokeURLs | Specifies or retrieves a value indicating whether URL events should start a Web browser.
mute | Specifies or retrieves a value indicating whether audio is muted.
playCount | Specifies or retrieves the number of times a media item will play.
rate | Specifies or retrieves the current playback rate
volume | Specifies or retrieves the current volume.

See Also

  • Settings Object


SLIDER Element

The SLIDER element provides a way to create and manipulate a simple horizontal or vertical slider control. The following tables list its attributes and event handlers.

The SLIDER element supports the following attributes.

Attribute | Description
backgroundColor | Specifies or retrieves the background color of the slider control.
backgroundEndColor | Specifies or retrieves the background ending color of the slider control.
backgroundHoverImage | Specifies or retrieves the background image of the slider that appears when hovering over it with the mouse.
backgroundImage | Specifies or retrieves the default background image of the slider.
borderSize | Specifies or retrieves the border size in pixels.
cursor | Specifies or retrieves a value indicating which type of cursor appears when the mouse is over the slider control.
direction | Specifies or retrieves the direction that slider images are laid out.
disabledColor | Specifies or retrieves the disabled color of the slider control.
disabledImage | Specifies or retrieves the image of the slider that appears when the control is disabled.
foregroundColor | Specifies or retrieves the foreground color of the slider control.
foregroundEndColor | Specifies or retrieves the foreground ending color of the slider control.
foregroundHoverImage | Specifies or retrieves the foreground image of the slider that appears when hovering over it with the mouse.
foregroundImage | Specifies or retrieves the default foreground image of the slider.
foregroundProgress | Specifies or retrieves the current position of the foreground progress bar as a percentage of the slider area.
max | Specifies or retrieves the maximum value of the range defined by the slider control.
min | Specifies or retrieves the minimum value of the range defined by the slider control.
slide | Specifies or retrieves a value indicating whether the foreground image slides over the background image.
thumbDisabledImage | Specifies or retrieves the disabled thumb image of the slider control.
thumbDownImage | Specifies or retrieves the image representing the down state of the thumb.
thumbHoverImage | Specifies or retrieves the image of the thumb that appears when hovering over it with the mouse.
thumbImage | Specifies or retrieves the image that will be used to represent the current position of the slider.
tiled | Specifies or retrieves a value indicating whether the slider images will be tiled.
toolTip | Specifies or retrieves the ToolTip text for the slider control.
transparencyColor | Specifies or retrieves the transparent color of the slider images.
useForegroundProgress | Specifies or retrieves a value indicating whether the foreground progress bar will be used.
value | Specifies and retrieves the current position of the slider.

The following event handlers can be implemented in the SLIDER element.

Event handler | Description
onDragBegin | Handles an event that occurs when the user clicks and holds the left mouse button down and begins to drag the mouse.
onDragEnd | Handles an event that occurs when the left mouse button is released after a dragging operation.
onPositionChange | Handles an event that occurs when the position of the slider changes as a result of the user clicking or dragging.

The ambient attributes and ambient events are also supported by this element.


SLIDER.backgroundColor

The backgroundColor attribute specifies or retrieves the background color of the slider control.

Syntax

elementID.backgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

A basic slider control can be constructed by specifying backgroundColor or backgroundImage, and foregroundColor or foregroundImage.

When using the colors, the dimensions of the slider control define the area filled by the background color. The foreground color covers the background color as the slider position increases.

To make a gradient fill of the area occupied by the background or foreground color, specify the backgroundEndColor or foregroundEndColor attributes.

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.backgroundEndColor
  • SLIDER.backgroundImage
  • SLIDER.foregroundColor
  • SLIDER.foregroundEndColor
  • SLIDER.foregroundImage
  • Color Reference


SLIDER.backgroundEndColor

The backgroundEndColor attribute specifies or retrieves the background ending color of the slider control.

Syntax

elementID.backgroundEndColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

The backgroundEndColor is used in conjunction with a backgroundColor. The effect created is a gradient fade from the backgroundColor to the backgroundEndColor.

See Also

  • SLIDER Element
  • SLIDER.backgroundColor
  • Color Reference


SLIDER.backgroundHoverImage

The backgroundHoverImage attribute specifies or retrieves the background image of the slider that appears when hovering over it with the mouse.

Syntax

elementID.backgroundHoverImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. If it is not specified, the backgroundImage will be used.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element


SLIDER.backgroundImage

The backgroundImage attribute specifies or retrieves the background image of the slider.

Syntax

elementID.backgroundImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. When using images to construct a slider, the backgroundImage is used for the main slider image. The thumbImage represents the actual slider and can be moved using the mouse. At the thumbImage slider there is an invisible line where the background image is displayed on one side of the line, and the foreground image is displayed on the other side.

When the thumbImage slider is moved with the mouse, if slide is set to true, the foreground image slides along as if being pulled by the slider to cover the background image. If slide is set to false, the foreground image does not move, but is revealed in place, as if the slider is moving the background image off the foreground image.

If the tiled attribute is set to true and the background image is smaller than the slider control, the image will be tiled either horizontally or vertically depending on the direction attribute. If the borderSize attribute is set to a value greater than zero, the number specified will be the number of pixels from the left and right or top and bottom of the image (again, depending on the direction attribute) that will be reserved for the borders of the slider control. In this case, only the central portion of the image is used for tiling the remainder of the control.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element
  • SLIDER.foregroundImage
  • SLIDER.slide
  • SLIDER.thumbImage


SLIDER.borderSize

The borderSize attribute specifies or retrieves the border width in pixels.

Syntax

elementID.borderSize

Possible Values

This attribute is a read/write Number (long) representing the border width in pixels. The default value is zero.

Remarks

This attribute defines an offset from the beginning and end of the slider control—that is, from the left and right if the direction attribute is set to “horizontal”, and from the top and bottom if it is set to “vertical”. These offset positions dictate the minimum and maximum positions of the slider thumb, beyond which the foreground color or image will not be applied.

If a background image is used with the tiled attribute set to true, the offset is applied to the image, dictating the amount of the image (either from the left and right or from the top and bottom) to be used for the beginning and end borders of the slider control, with the central portion of the image being tiled throughout the remainder. In this way, a small background image can be used to cover the full length of a larger slider control.

See Also

  • SLIDER Element
  • SLIDER.foregroundColor
  • SLIDER.foregroundImage
  • SLIDER.thumbImage
  • SLIDER.tiled


SLIDER.cursor

The cursor attribute specifies or retrieves a value indicating which cursor appears when the mouse is over the slider control.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Platform-dependent cursor (usually an arrow).
hand | Default. Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

See Also

  • SLIDER Element


SLIDER.direction

The direction attribute specifies or retrieves the direction that slider images are laid out.

Syntax

elementID.direction

Possible Values

This attribute is a read/write String.

Value | Description
horizontal | Default. The minimum position is at the left, and the maximum position is at the right.
vertical | The minimum position is at the bottom, and the maximum position is at the top.

Remarks

The fill or movement of the foregroundColor or foregroundImage is along the vertical or horizontal axis according to the specified value.

See Also

  • SLIDER Element
  • SLIDER.foregroundColor
  • SLIDER.foregroundImage


SLIDER.disabledColor

The disabledColor attribute specifies or retrieves the color of the slider control when it is disabled.

Syntax

elementID.disabledColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

When the slider control is specified using foreground and background colors, the disabled color specifies the color of the control when enabled is set to false.

See Also

  • SLIDER Element
  • AmbientAttributes.enabled
  • Color Reference


SLIDER.disabledImage

The disabledImage attribute specifies or retrieves the image of the slider that is used when the slider control is disabled.

Syntax

elementID.disabledImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The disabledImage is optional. If it is not provided, the backgroundImage is used for all disabled states. When a slider control is disabled, no foreground image is visible.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element
  • SLIDER.backgroundImage


SLIDER.foregroundColor

The foregroundColor attribute specifies or retrieves the foreground color of the slider control.

Syntax

elementID.foregroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. The default value is "white".

Remarks

A basic slider control can be constructed by specifying one of two pairs of attributes: the backgroundColor and foregroundColor, or the backgroundImage and foregroundImage.

When you construct a slider control using the colors, the dimensions of the slider control define the area filled by the background color. The foreground color covers the background color as the slider position increases.

To make a gradient fill in the area occupied by the background or foreground color, specify the backgroundEndColor or foregroundEndColor attributes.

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.backgroundColor
  • SLIDER.backgroundEndColor
  • SLIDER.foregroundEndColor
  • SLIDER.foregroundImage
  • Color Reference


SLIDER.foregroundEndColor

The foregroundEndColor attribute specifies or retrieves the foreground ending color of the slider control.

Syntax

elementID.foregroundEndColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

The foregroundEndColor is used in conjunction with a foregroundColor. The effect created is a gradient fade from the foregroundColor to the foregroundEndColor.

See Also

  • SLIDER Element
  • SLIDER.foregroundColor
  • Color Reference


SLIDER.foregroundHoverImage

The foregroundHoverImage attribute specifies or retrieves the foreground image of the slider that appears when hovering over it with the mouse.

Syntax

elementID.foregroundHoverImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The foregroundHoverImage is optional. If it is not provided, the backgroundImage is used.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element


SLIDER.foregroundImage

The foregroundImage attribute specifies or retrieves the foreground image of the slider.

Syntax

elementID.foregroundImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

This attribute is optional. When using images to construct a slider control, the backgroundImage is used for the main slider image. The thumbImage represents the actual slider and can be moved using the mouse. At the thumbImage slider there is an invisible line where the background image is displayed on one side of the line, and the foreground image is displayed on the other side.

When the thumbImage slider is moved with the mouse, if slide is set to true, the foreground image slides along as if being pulled by the slider to cover the background image. If slide is set to false, the foreground image does not move, but is revealed in place, as if the slider is moving the background image off the foreground image.

If the tiled attribute is set to true and the foreground image is smaller than the foreground area of the slider control, the image will be tiled either horizontally or vertically, depending on the direction attribute, to fill the available space.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element
  • SLIDER.backgroundImage
  • SLIDER.slide
  • SLIDER.thumbImage
  • SLIDER.value


SLIDER.foregroundProgress

The foregroundProgress attribute specifies or retrieves the current position of the foreground progress bar as a percentage of the slider area.

Syntax

elementID.foregroundProgress

Possible Values

This attribute is a read/write Number (float) ranging from 0 to 100.

Example

<SLIDER
  id=”seek”
  backgroundColor=”blue”
  foregroundColor=”red”
  thumbImage=”seekthumb.bmp”
  min=”0”
  max=”wmpprop:player.currentMedia.duration”
  value=”wmpprop:player.controls.currentPosition”
  useForegroundProgress=”true”
  foregroundProgress=”wmpprop:player.network.downloadProgress”
  ondragend=”player.controls.currentposition=value”
/>

Remarks

This attribute is used primarily to track the download progress of a media file while simultaneously tracking the current play position of the file using the value attribute. The position of the slider thumb is constrained to the area of the foreground progress. This allows interactive seeking to take place only within the available portion of a downloading file.

To use this functionality, the useForegroundProgress attribute must be set to true.

See Also

  • SLIDER Element
  • SLIDER.min
  • SLIDER.max
  • SLIDER.useForegroundProgress
  • SLIDER.value


SLIDER.max

The max attribute specifies or retrieves the maximum value of the range defined by the slider control.

Syntax

elementID.max

Possible Values

This attribute is a read/write Number (float) with a default value of 100.

Remarks

The value specified for max must be greater than the one for min.

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.min
  • SLIDER.value


SLIDER.min

The min attribute specifies or retrieves the minimum value of the range defined by the slider control.

Syntax

elementID.min

Possible Values

This attribute is a read/write Number (float) with a default value of zero.

Remarks

The value specified for min must be less than the one for max.

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.max
  • SLIDER.value


SLIDER.onDragBegin

The onDragBegin event handler handles an event that occurs when the user clicks and holds the left mouse button down and begins to drag the mouse.

Syntax

onDragBegin

See Also

  • SLIDER Element


SLIDER.onDragEnd

The onDragEnd event handler handles an event that occurs when the left mouse button is released after a dragging operation.

Syntax

onDragEnd

See Also

  • SLIDER Element


SLIDER.onPositionChange

The onPositionChange event handler handles an event that occurs when the position of the slider changes as a result of the user clicking or dragging.

Syntax

onPositionChange

Remarks

If the position of the slider changes as a result of the value attribute being modified in script, this event is not fired. To accommodate this possibility, implement the value_onchange event handler instead.

See Also

  • SLIDER Element


SLIDER.slide

The slide attribute specifies or retrieves a value indicating whether the foreground image slides over the background image or is gradually revealed in a static position over the background image.

Syntax

elementID.slide

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. The foreground image slides over the background image.
false | The foreground image is revealed in place over the background image.

Remarks

When the thumbImage slider is moved with the mouse, if slide is set to true, the foreground image slides along as if being pulled by the slider to cover the background image. If slide is set to false, the foreground image does not move, but is revealed in place, as if the slider is moving the background image off the foreground image.

See Also

  • SLIDER Element
  • SLIDER.backgroundImage
  • SLIDER.foregroundImage


SLIDER.thumbDisabledImage

The thumbDisabledImage attribute specifies or retrieves the thumb image of the slider control that is used when the control is disabled.

Syntax

elementID.thumbDisabledImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The thumbDisabledImage is optional. If it is not specified, thumbImage is used instead.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element
  • AmbientAttributes.enabled
  • SLIDER.thumbImage


SLIDER.thumbDownImage

The thumbDownImage attribute specifies or retrieves the image representing the down state of the thumb.

Syntax

elementID.thumbDownImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The thumbDownImage is optional and is the image used to represent the down state of the thumbImage. If a thumbDownImage is not provided, the slider will use the thumbImage.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element
  • SLIDER.thumbImage


SLIDER.thumbHoverImage

The thumbHoverImage attribute specifies or retrieves the image of the thumb that appears when hovering over it with the mouse.

Syntax

elementID.thumbHoverImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The thumbHoverImage is optional. If it is not provided, the slider control will not change appearance when the mouse hovers over it.

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

See Also

  • SLIDER Element


SLIDER.thumbImage

The thumbImage attribute specifies or retrieves the image that will be used to represent the current position of the slider.

Syntax

elementID.thumbImage

Possible Values

This attribute is a read/write String containing the name of an image file.

Remarks

The thumbImage specifies the image that will be used to represent current position, as well as indicate that the user can take action with the control. If no thumb image is specified, the slider is non-interactive.

The thumb image is centered in the narrow dimension of the slider control. If the thumb image is narrower than the control, the image appears in the middle of the background. If the thumb image is larger than the control, the ends of the image are cut off.

The position of the slider is specified by the center of the thumb image. If borderSize is zero, only half the thumb image will be visible at the beginning and end slider positions. To prevent this, set borderSize to a value greater than or equal to half the width of the thumb image (or half the height if direction is set to “vertical”).

The supported formats are BMP, JPG, PNG, and GIF (not including animated GIFs).

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.borderSize
  • SLIDER.direction


SLIDER.tiled

The tiled attribute specifies or retrieves a value indicating whether the slider image will be tiled.

Syntax

elementID.tiled

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. The image bitmap will be repeated until it fills the entire region of the control.
false | The image will not be tiled.

Remarks

This attribute applies only if you are using foreground and background images to define a slider control. If the images are smaller than the defined area of the slider, and the tiled attribute is set to true, the images will be repeated until they fill the entire length of the control.

You may wish to use this attribute in conjunction with the borderSize attribute. The borderSize attribute allows you to define a border that is not repeated during tiling.

See Also

  • SLIDER Element
  • SLIDER.backgroundImage
  • SLIDER.borderSize
  • SLIDER.foregroundImage


SLIDER.toolTip

The toolTip attribute specifies or retrieves the ToolTip text for the slider control.

Syntax

elementID.toolTip

Possible Values

This attribute is a read/write String with a maximum length of 1024 characters. It has no default value.

Remarks

The ToolTip is optional; if it is not defined, it does not appear.

See Also

  • SLIDER Element


SLIDER.transparencyColor

The transparencyColor attribute specifies or retrieves the transparent color of the slider control background and foreground images.

Syntax

elementID.transparencyColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Remarks

Any part of the image containing the transparencyColor will allow the background to show through.

Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended when transparencyColor is used.

See Also

  • SLIDER Element
  • Color Reference


SLIDER.useForegroundProgress

The useForegroundProgress attribute specifies or retrieves a value indicating whether the foreground progress bar will be used.

Syntax

elementID.useForegroundProgress

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Use foreground progress.
false | Default. Do not use foreground progress.

Remarks

This attribute allows the use of the foregroundProgress attribute, which is used primarily to track the download progress of a media file while simultaneously tracking the current play position of the file using the value attribute.

See Also

  • SLIDER Element
  • SLIDER.foregroundProgress
  • SLIDER.value


SLIDER.value

The value attribute specifies or retrieves the current position of the slider.

Syntax

elementID.value

Possible Values

This attribute is a read/write Number (float) with a default value of min.

Remarks

The value should always be greater than or equal to min and less than or equal to max. If you specify a value outside this range, value and the position of the slider are not changed.

Example

Please see the CUSTOMSLIDER.positionImage attribute for a sample illustrating how the attributes of the SLIDER element are used.

See Also

  • SLIDER Element
  • SLIDER.min


SUBVIEW Element

The SUBVIEW element provides a way to manipulate a portion of a skin, for example, to provide a control panel that can be hidden when it is not being used.

The SUBVIEW element supports the following attributes, which are defined under the VIEW element.

Attribute | Description
backgroundColor | Specifies or retrieves the background color of the SUBVIEW control.
backgroundImage | Specifies or retrieves the background image of the SUBVIEW control.
backgroundTiled | Specifies or retrieves a value indicating whether the background image of the SUBVIEW control is tiled.
transparencyColor | Specifies or retrieves the transparency color of the background image.

This element also supports the ambient attributes, except where noted, and the following ambient event handlers: onendmove and onresize.

See Also

  • VIEW Element


TEXT Element

The TEXT element provides a way to create and control the appearance of text within a skin.

The TEXT element supports the following attributes.

Attribute | Description
backgroundColor | Specifies or retrieves the background color for the Text control.
cursor | Specifies or retrieves a value indicating which cursor appears when the mouse is over the Text control.
disabledBackgroundColor | Specifies or retrieves the background color used for the Text control when it is disabled.
disabledFontStyle | Specifies or retrieves the font style used for the Text control when it is disabled.
disabledForegroundColor | Specifies or retrieves the text color used when the Text control is disabled.
fontFace | Specifies or retrieves the typeface for the Text control.
fontSize | Specifies or retrieves the font size for the Text control.
fontSmoothing | Specifies or retrieves a value indicating whether font smoothing is enabled.
fontStyle | Specifies or retrieves the font style for the Text control.
foregroundColor | Specifies or retrieves the text color for the Text control.
hoverBackgroundColor | Specifies or retrieves the background color used for the Text control when the mouse cursor hovers over it.
hoverFontStyle | Specifies or retrieves the font style used for the Text control when the mouse cursor hovers over it.
hoverForegroundColor | Specifies or retrieves the text color used for the Text control when the mouse cursor hovers over it.
justification | Specifies or retrieves the alignment of the text within the Text control.
scrolling | Specifies or retrieves a value indicating whether the text scrolls.
scrollingAmount | Specifies or retrieves the number of pixels that the text moves during each scrolling movement.
scrollingDelay | Specifies or retrieves the time delay between scrolling movements.
scrollingDirection | Specifies or retrieves the direction of the scrolling text.
textWidth | Retrieves the width in pixels of the string contained in the value attribute.
toolTip | Specifies or retrieves the ToolTip text for the text control.
value | Specifies or retrieves the text that is displayed in the Text control.
wordWrap | Specifies or retrieves a value indicating whether word wrapping is enabled or disabled.

The ambient attributes and ambient events are also supported by this element.


TEXT.backgroundColor

The backgroundColor attribute specifies or retrieves the background color for the Text control.

Syntax

elementID.backgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value or the value “none”. It has a default value of “none”, which means the background is transparent.

Remarks

The background color is set for the height and width of the control. If height and width are not set, the background color is set to the height and width of the text.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • Color Reference


TEXT.cursor

The cursor attribute specifies or retrieves a value indicating which cursor appears when the mouse is over the Text control.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Default. Platform-dependent cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element


TEXT.disabledBackgroundColor

The disabledBackgroundColor attribute specifies or retrieves the background color used for the Text control when it is disabled.

Syntax

elementID.disabledBackgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value.

Remarks

If the disabledBackgroundColor is not specified, the backgroundColor is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.backgroundColor
  • Color Reference


TEXT.disabledFontStyle

The disabledFontStyle attribute specifies or retrieves the font style used for the Text control when it is disabled.

Syntax

elementID.disabledFontStyle

Possible Values

This attribute is a read/write String containing one or more of the following values.

Value | Description
Bold | Bold font style.
Italic | Italic font style.
Underline | Underline font style.
Strikeout | Strikeout font style.
Normal | Normal font style.

Remarks

Any combination of the values can be used, separated with spaces. The Normal style has priority over all other values, and any others specified along with Normal will be ignored.

If disabledFontStyle is not specified, fontStyle is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.fontStyle


TEXT.disabledForegroundColor

The disabledForegroundColor attribute specifies or retrieves the text color used for the Text control when it is disabled.

Syntax

elementID.disabledForegroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value.

Remarks

If disabledForegroundColor is not specified, foregroundColor is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.foregroundColor
  • Color Reference


TEXT.fontFace

The fontFace attribute specifies or retrieves the typeface for the Text control.

Syntax

elementID.fontFace

Possible Values

This attribute is a read/write String with a default value of “Tahoma”.

Remarks

This attribute can be the name of any valid font available on Windows. Windows Media Player will not support installing fonts, so choose a font that you know will be on the intended system.

If the fontFace specified is not available on the user’s system, the Text control defaults to the Windows system font.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.fontSize


TEXT.fontSize

The fontSize attribute specifies or retrieves the font size for the Text control.

Syntax

elementID.fontSize

Possible Values

This attribute is a read/write Number (long) specifying the font size in points. It has a default value of 10.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.fontFace


TEXT.fontSmoothing

The fontSmoothing attribute specifies or retrieves a value indicating whether font smoothing is enabled.

Syntax

elementID.fontSmoothing

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Font smoothing is enabled.
false | Default. Font smoothing is disabled.

Remarks

Font smoothing uses the anti-aliasing feature of the operating system. If font smoothing is enabled and the operating system supports anti-aliasing, the control attempts to anti-alias the text. Not all fonts support anti-aliasing.

Operating Systems that support anti-aliasing:

  • Windows 98
  • Windows 2000
  • Windows 95 with Plus!
  • Windows NT 4.0

Warning: Font smoothing over a transparent color may cause the transparent color to blend into the characters. It is not recommended that you use fontSmoothing if the text will display over a transparency.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element


TEXT.fontStyle

The fontStyle attribute specifies or retrieves the font style for the Text control.

Syntax

elementID.fontStyle

Possible Values

This attribute is a read/write String containing one or more of the following values.

Value | Description
Bold | Bold font style.
Italic | Italic font style.
Underline | Underline font style.
Strikeout | Strikeout font style.
Normal | Default. Normal font style.

Remarks

Any combination of the values can be used, separated with spaces. The Normal style has priority over all other values, and any others specified along with Normal will be ignored.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element


TEXT.foregroundColor

The foregroundColor attribute specifies or retrieves the text color for the Text control.

Syntax

elementID.foregroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. The default value is “black”.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • Color Reference


TEXT.hoverBackgroundColor

The hoverBackgroundColor attribute specifies or retrieves the background color used for the Text control when the mouse cursor hovers over it.

Syntax

elementID.hoverBackgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value.

Remarks

If hoverBackgroundColor is not specified, the backgroundColor is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.backgroundColor
  • Color Reference


TEXT.hoverFontStyle

The hoverFontStyle attribute specifies or retrieves the font style used for the Text control when the mouse cursor hovers over it.

Syntax

elementID.hoverFontStyle

Possible Values

This attribute is a read/write String containing one or more of the following values.

Value | Description
Bold | Bold font style.
Italic | Italic font style.
Underline | Underline font style.
Strikeout | Strikeout font style.
Normal | Normal font style.

Remarks

Any combination of the values can be used, separated with spaces. The Normal style has priority over all other values, and any others specified along with Normal will be ignored.

If hoverFontStyle is not specified, fontStyle is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.fontStyle


TEXT.hoverForegroundColor

The hoverForegroundColor attribute specifies or retrieves the text color used for the Text control when the mouse cursor hovers over it.

Syntax

elementID.hoverForegroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value.

Remarks

If hoverForegroundColor is not specified, foregroundColor is used.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.foregroundColor
  • Color Reference


TEXT.justification

The justification attribute specifies or retrieves the alignment of the text within the Text control.

Syntax

elementID.justification

Possible Values

This attribute is a read/write String.

Value | Description
Left | Default. Aligns the text to the left of the Text control.
Right | Aligns the text to the right of the Text control.
Center | Aligns the text to the horizontal center of the Text control.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element


TEXT.scrolling

The scrolling attribute specifies or retrieves a value indicating whether the text scrolls.

Syntax

elementID.scrolling

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Scrolling is enabled.
false | Default. Scrolling is disabled.

Remarks

The scrolling feature provides a two-space buffer between the end of the text and the beginning of the repeated line.

The justification attribute specifies where the text first appears before the scrolling begins.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.justification
  • TEXT.scrollingAmount
  • TEXT.scrollingDelay
  • TEXT.scrollingDirection


TEXT.scrollingAmount

The scrollingAmount attribute specifies or retrieves the number of pixels that the text moves during each scrolling movement.

Syntax

elementID.scrollingAmount

Possible Values

This attribute is a positive read/write Number (int) with a default value of 6.

Remarks

For smooth scrolling, scrollingAmount should be small. For fast drawing with big gaps, the scrollingAmount should be larger. If scrolling="false", scrollingAmount is ignored.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.scrolling


TEXT.scrollingDelay

The scrollingDelay attribute specifies or retrieves the time delay between scrolling movements.

Syntax

elementID.scrollingDelay

Possible Values

This attribute is a read/write Number (int) specifying the delay in milliseconds. It has a minimum value of 30, and a default value of 85. If a value less than the minimum is specified, the default is used.

Remarks

If scrolling is set to false, scrollingDelay is ignored.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.scrolling


TEXT.scrollingDirection

The scrollingDirection attribute specifies or retrieves the direction of the scrolling text.

Syntax

elementID.scrollingDirection

Possible Values

This attribute is a read/write String.

Value | Description
Left | Default. Scroll from right to left.
Right | Scroll from left to right.

Remarks

If scrolling is set to false, scrollingDirection is ignored.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.scrolling


TEXT.textWidth

The textWidth attribute retrieves the width in pixels of the text contained in the value attribute.

Syntax

elementID.textWidth

Possible Values

This attribute is a read-only Number (int).

Remarks

The value returned is based on the fontFace, fontSize, and fontStyle attributes as well as on the actual characters in the value attribute string.

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.fontFace
  • TEXT.fontSize
  • TEXT.fontStyle
  • TEXT.value


TEXT.toolTip

The toolTip attribute specifies or retrieves the ToolTip text for the text control.

Syntax

elementID.toolTip

Possible Values

This attribute is a read/write String with a maximum length of 1024 characters. It has no default value.

Remarks

If this attribute is not specified, and the text in the value attribute is truncated in the Text control, or wordWrap is set to true, the ToolTip will display the full text of the value attribute.

If no ToolTip is desired, set toolTip to "" (the empty String).

Example

Please see the value attribute for a sample illustrating how the attributes of the TEXT element are used.

See Also

  • TEXT Element
  • TEXT.value
  • TEXT.wordWrap


TEXT.value

The value attribute specifies or retrieves the text that is displayed in the Text control.

Syntax

elementID.value

Possible Values

This attribute is a read/write String.

Remarks

If the width of the Text control is insufficient to contain the text provided, the text is cropped, and an ellipsis is shown to illustrate the fact. If the toolTip attribute has not been set, the complete text will then appear as a ToolTip when the cursor hovers over the control.

If a width is not specified, the default width for the control is the width of the string.

If the height of the control is not specified, the default height is one line.

If the wordWrap attribute is set to true and the height of the control is enough to accommodate another line of text, the text wraps to a subsequent line. Wrapping only occurs between words. Line breaks may also be forced, as explained under wordWrap.

Example

The following sample is a complete skin definition file that illustrates how the attributes of the TEXT element are used. It can be found in the Samples directory that was installed with the SDK.

<THEME>
  <VIEW
    height = "175"
  >
    <TEXT
      width = "150"
      fontSize = "30"
      hoverFontStyle = "Bold"
      hoverForegroundColor = "red"
      disabledForegroundColor = "#CCCCCC"
      justification = "Center"
      value = "Play"
      cursor = "hand"
      enabled = "wmpenabled:player.controls.play"
      onClick = "JScript: player.URL='file:..\\media\\laure.wma';"
    />
    <TEXT
      top = "50"
      width = "150"
      fontSize = "30"
      hoverFontStyle = "Bold"
      hoverForegroundColor = "red"
      disabledForegroundColor = "#CCCCCC"
      justification = "Center"
      value = "Stop"
      cursor = "hand"
      enabled = "wmpenabled:player.controls.stop"
      onClick = "JScript: player.controls.stop();"
    />
    <TEXT
      top = "100"
      width = "150"
      fontSize = "30"
      hoverFontStyle = "Bold"
      hoverForegroundColor = "red"
      justification = "Center"
      value = "Close"
      cursor = "hand"
      onClick = "JScript: view.close();"
    />
    <TEXT
      top = "30"
      left = "120"
      width = "200"
      fontSize = "20"
      fontStyle = "Underline"
      justification = "Center"
      value = "Volume"
    />
    <TEXT
      top = "60"
      left = "120"
      width = "200"
      fontSize = "40"
      justification = "Center"
      value = "wmpprop:player.settings.volume"
    />
    <TEXT
      top = "65"
      left = "142"
      width = "40"
      fontSize = "30"
      hoverFontStyle = "Bold"
      hoverForegroundColor = "red"
      justification = "Center"
      value = "-"
      cursor = "hand"
      toolTip = "decrease volume"
      onClick = "player.settings.volume = player.settings.volume - 5"
    />
    <TEXT
      top = "65"
      left = "260"
      width = "40"
      fontSize = "30"
      hoverFontStyle = "Bold"
      hoverForegroundColor = "red"
      justification = "Center"
      value = "+"
      cursor = "hand"
      toolTip = "increase volume"
      onClick = "player.settings.volume = player.settings.volume + 5"
    />
    <TEXT
      top = "155"
      width = "300"
      height = "30"
      fontFace = "System"
      backgroundColor = "blue"
      foregroundColor = "white"
      justification = "Center"
      scrolling = "true"
      scrollingAmount = "1"
      scrollingDelay = "50"
      value = "wmpprop:player.status"
    />
  </VIEW>
</THEME>

See Also

  • TEXT Element
  • TEXT.toolTip
  • TEXT.wordWrap


TEXT.wordWrap

The wordWrap attribute specifies or retrieves a value indicating whether word wrap is enabled or disabled.

Syntax

elementID.wordWrap

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Word wrap is enabled.
false | Default. Word wrap is disabled. If the text does not fit within the control, the text is cropped.

Remarks

The Text control does not split words apart. If a word extends beyond the width of the control, word wrap is employed to move the word to the next line. If a single word is longer than the control width, that word is clipped and occupies a single line.

If the width attribute is not specified, wordWrap is ignored and the Text control will resize rather than wrapping the text.

If line breaks are desired in particular locations, they must be explicitly specified in value using ‘&#13;’ or ‘\r’. If the latter form is used when specifying the value directly, the string must be prefixed with ‘JScript:’ and the actual value must be surrounded by single quotes, as shown below. This is not necessary if the value is set dynamically from within an event handler.

If wordWrap is set to true and toolTip is not specified, the ToolTip will display the full text of the value attribute. If no ToolTip is desired, set toolTip to "" (the empty String).

Example

<THEME>
  <VIEW>
    <TEXT
      width = "50"
      height = "200"
      wordWrap = "true"
      backgroundColor = "blue"
      foregroundColor = "white"
      value = "This is a test.&#13;&#13;It is only a test."
    />
    <TEXT
      width = "50"
      height = "200"
      left = "100"
      wordWrap = "true"
      backgroundColor = "green"
      foregroundColor = "white"
      value = "JScript:'This is a test.\r\rIt is only a test.'"
    />
  </VIEW>
</THEME>

See Also

  • TEXT Element
  • TEXT.toolTip
  • TEXT.value
  • AmbientAttributes.width


THEME Element

The THEME element is the parent-level element of a skin, containing all other elements. Within a script, it is accessed through the theme global attribute, rather than through an id attribute specified in the THEME element.

The THEME element supports the following attributes.

Attribute | Description
author | Specifies or retrieves the name of the author of the skin.
authorVersion | Specifies or retrieves the version number of the skin as assigned by the author.
copyright | Specifies or retrieves the copyright string for the skin.
currentViewID | Specifies or retrieves the currently displayed VIEW.
title | Specifies or retrieves the title of the skin.
version | Specifies or retrieves the Windows Media Player version number for which the skin was authored.

The THEME element supports the following methods.

Method | Description
closeView | Closes an open VIEW.
loadPreference | Loads a preference from the registry.
logString | Logs a user-defined string to the error file, if logging is enabled.
openDialog | Opens a file dialog box.
openView | Opens a VIEW in a new window.
savePreference | Saves a preference in the registry.
showErrorDialog | Displays the standard error dialog box.

The THEME element does not support event handlers.


THEME.author

The author attribute specifies or retrieves the name of the author of the skin.

Syntax

theme.author

Possible Values

This attribute is a read/write String with no default value.

See Also

  • THEME Element
  • THEME.authorVersion


THEME.authorVersion

The authorVersion attribute specifies or retrieves the version number of the skin as assigned by the author.

Syntax

theme.authorVersion

Possible Values

This attribute is a read-only String with no default value.

See Also

  • THEME Element
  • THEME.author


THEME.closeView

The closeView method closes an open VIEW.

Syntax

theme.closeView(theView)

Parameters

theView

A String specifying the id of the VIEW to close.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW>
    <TEXT value="open"
        onclick="jscript:theme.openView('newView')"/>
    <TEXT top="30" value="close"
        onclick="jscript:theme.closeView('newView')"/>
  </VIEW>
  <VIEW id="newView"/>
</THEME>

See Also

  • THEME Element
  • THEME.openView


THEME.copyright

The copyright attribute specifies or retrieves the copyright string for the skin.

Syntax

theme.copyright

Possible Values

This attribute is a read/write String with no default value.

See Also

  • THEME Element


THEME.currentViewID

The currentViewID attribute specifies or retrieves the currently displayed VIEW.

Syntax

theme.currentViewID

Possible Values

This attribute is a read/write String specifying the id of the current VIEW. It has no default value.

Example

<THEME currentViewID="startView">
  <VIEW>
    <TEXT value="this would have been the default view"/>
  </VIEW>
  <VIEW id="startView">
    <TEXT value="go to new view"
        onclick="jscript:theme.currentViewID='newView'"/>
  </VIEW>
  <VIEW id="newView">
    <TEXT value="new view"/>
  </VIEW>
</THEME>

Remarks

Specifying currentViewID automatically closes the existing currentView (pointed to by the view global attribute) and opens the specified VIEW.

See Also

  • THEME Element


THEME.loadPreference

The loadPreference method loads a preference from the registry.

Syntax

theme.logString(theKey)

Parameters

theKey

A String specifying the key of the preference value to load.

Return Values

This method returns a String.

Remarks

A preference is a key/value pair that can be stored in the registry in order to retain information about the state of the Windows Media Player between runs. This feature can be used, for example, to save customization settings so that they won’t have to be re-entered each time the Windows Media Player is started.

See Also

  • THEME Element


THEME.logString

The logString method logs a user-defined string to the error file, if logging is enabled.

Syntax

theme.logString(message)

Parameters

message

A String specifying the message to log.

Return Values

This method does not return a value.

See Also

  • THEME Element


THEME.openDialog

The openDialog method opens a file dialog box.

Syntax

theme.openDialog(dialogType, parameters)

Parameters

dialogType

A String that specifies the type of dialog box. Must be set to “FILE_OPEN”.

parameters

A String that can be used for additional information. Must be set to “FILES_ALLMEDIA”.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1”
    backgroundImage=“greenstone.bmp”
    width=500 height=300 author=“Microsoft Corp.”>
    <BUTTON
      id=“Open”
      image=“Open.png”
      onclick=“jscript:
        player.URL = theme.openDialog(‘FILE_OPEN’,‘FILES_ALLMEDIA’)”>
    </BUTTON>
  </VIEW>
</THEME>

Remarks

This method can be used for files on the local hard drives or on network drives.

See Also

  • THEME Element


THEME.openView

The openView method opens a VIEW in a new window.

Syntax

theme.openView(theView)

Parameters

theView

A String specifying the id of the VIEW to open.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW>
    <TEXT value="open"
        onclick="jscript:theme.openView('newView')"/>
    <TEXT top="30" value="close"
        onclick="jscript:theme.closeView('newView')"/>
  </VIEW>
  <VIEW id="newView"/>
</THEME>

See Also

  • THEME Element
  • THEME.closeView


THEME.savePreference

The savePreference method saves a preference in the registry.

Syntax

theme.savePreference(theKey, theValue)

Parameters

theKey

A String specifying the key of the preference value to save.

theValue

A String specifying the value to save.

Return Values

This method does not return a value.

Example

<Theme id=”myskin”>
  <View
    id=”View1”
    onclose=”jscript:myskin.savePreference(‘drawer1’,‘open’);
             myskin.savePreference(‘drawer2’,‘close’)”>
  </View>
</Theme>

Remarks

A preference is a key/value pair that can be stored in the registry in order to retain information about the state of the Windows Media Player between runs. This feature can be used, for example, to save customization settings so that they won’t have to be re-entered each time the Windows Media Player is started.

See Also

  • THEME Element


THEME.showErrorDialog

The showErrorDialog method displays the standard error dialog box.

Syntax

theme.showErrorDialog()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Remarks

If Settings.enableErrorDialogs is false, this method can be used to programmatically display the error dialog. If there are no errors in the error queue, the error dialog box is not shown.

See Also

  • THEME Element
  • Settings.enableErrorDialogs


THEME.title

The title attribute specifies or retrieves the title of the skin.

Syntax

theme.title

Possible Values

This attribute is a read/write String with no default value.

See Also

  • THEME Element


THEME.version

The version attribute specifies or retrieves the Windows Media Player version number for which the skin was authored.

Syntax

theme.version

Possible Values

This attribute is a read/write Number with a default value of “1.0”.

See Also

  • THEME Element


VIDEO Element

The VIDEO element provides a way to manipulate a video window in a skin, using the following attributes and events.

The VIDEO element supports the following attributes.

Attribute | Description
backgroundColor | Specifies or retrieves the background color of the Video control.
cursor | Specifies or retrieves the cursor value that is used when the mouse is over a clickable area of the video.
fullScreen | Specifies or retrieves a value indicating whether the video is displayed in full-screen mode. Can only be set at run time.
maintainAspectRatio | Specifies or retrieves a value indicating whether the video will maintain the aspect ratio when trying to fit within the width and height defined for the control.
shrinkToFit | Specifies or retrieves a value indicating whether the video will shrink to the width and height defined for the Video control.
stretchToFit | Specifies or retrieves a value indicating whether the video will stretch itself to the width and height defined for the Video control.
toolTip | Specifies or retrieves the ToolTip text for the video window.
windowless | Specifies or retrieves a value indicating whether the Video control will be windowed or windowless; that is, whether the entire rectangle of the control will be visible at all times or can be clipped. Can only be set at design time.
zoom | Specifies the percentage by which to scale the video.

The following event handlers can be implemented in the VIDEO element.

Event handler | Description
onvideoend | Handles an event that occurs when the video stops rendering and is unloaded.
onvideostart | Handles an event that occurs when the video is loaded and begins to render.

The ambient attributes and ambient events are also supported by this element, except where noted.


VIDEO.backgroundColor

The backgroundColor attribute specifies or retrieves the background color of the Video control.

Syntax

elementID.backgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value or the value “none”. It has a default value of “none”, which means that if there is no video associated with the video control, the Video control is transparent and the background shows through.

Remarks

When the video is smaller than the window and stretchToFit is false, the background color appears around the video.

See Also

  • VIDEO Element
  • VIDEO.stretchToFit
  • Color Reference


VIDEO.cursor

The cursor attribute specifies or retrieves the cursor value that is used when the mouse is over a clickable area of the video.

Syntax

elementID.cursor

Possible Values

This attribute is a read/write String.

Value | Description
system | Default. Platform-dependent cursor (usually an arrow).
hand | Hand.
help | Arrow with question mark indicating Help is available.
*.ani or *.cur | Any .ani or .cur file (must be in the same directory as the .wms file or be in the .wmz file).

See Also

  • VIDEO Element


VIDEO.fullScreen

The fullScreen attribute specifies or retrieves a value indicating whether the video is displayed in full-screen mode.

Syntax

elementID.fullScreen

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Video displays in full-screen mode.
false | Default. Video does not display in full-screen mode.

Remarks

This property can be specified only at run time, after a file has been loaded. It must therefore be set within a script event handler. The escape button is used to return to normal viewing.

See Also

  • VIDEO Element
  • VIDEO.maintainAspectRatio
  • VIDEO.shrinkToFit
  • VIDEO.stretchToFit


VIDEO.maintainAspectRatio

The maintainAspectRatio attribute specifies or retrieves a value indicating whether the video will maintain its aspect ratio when trying to fit within the width and height defined for the control.

Syntax

elementID.maintainAspectRatio

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. Video maintains its aspect ratio when resizing.
false | Video does not maintain its aspect ratio when resizing.

See Also

  • VIDEO Element


VIDEO.onvideoend

The onvideoend event handler handles an event that occurs when the video stops rendering and is unloaded.

Syntax

onvideoend

See Also

  • VIDEO Element


VIDEO.onvideostart

The onvideostart event handler handles an event that occurs when the video is loaded and begins to render.

Syntax

onvideostart

See Also

  • VIDEO Element


VIDEO.shrinkToFit

The shrinkToFit attribute specifies or retrieves a value indicating whether the video will shrink to the width and height defined for the Video control.

Syntax

elementID.shrinkToFit

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | Default. The video will shrink to fit the control.
false | The video will not shrink to fit the control.

Remarks

If no width or height is specified, this attribute is ignored.

See Also

  • VIDEO Element


VIDEO.stretchToFit

The stretchToFit attribute specifies a value indicating whether the video will stretch to the width and height defined for the Video control.

Syntax

elementID.stretchToFit

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | The video will stretch to fit the control.
false | Default. The video will not stretch to fit the control.

Remarks

If no width or height is specified, this attribute is ignored.

See Also

  • VIDEO Element


VIDEO.toolTip

The toolTip attribute specifies or retrieves the ToolTip text for the video window.

Syntax

elementID.toolTip

Possible Values

This attribute is a read/write String, which must not exceed 1024 characters in length. It has no default value.

See Also

  • VIDEO Element


VIDEO.windowless

The windowless attribute specifies or retrieves a value indicating whether the Video control will be windowed or windowless; that is, whether the entire rectangle of the control will be visible at all times or can be clipped. Can only be set at design time.

Syntax

elementID.windowless

Possible Values

This attribute is a Boolean specified at design time and read-only thereafter.

Value | Description
true | Video control will be windowless.
false | Default. Video control will be windowed.

Remarks

If a non-rectangular video window is desired, or if you want to cover any part of the video window with an image, this attribute must be set to true. This sacrifices some performance in order to do the necessary clipping.

Video playback is optimized for unclipped playback. In this case, the windowless attribute is set to false, and the entire video rectangle is always displayed. Any image covering the video window is ignored, and the video window has the highest-level z-order.

See Also

  • VIDEO Element


VIDEO.zoom

The zoom attribute specifies the percentage by which to scale the video.

Syntax

elementID.zoom

Possible Values

This attribute is a read/write Number (long) ranging from 1 to the maximum size accommodated by the width and height of the Video control. It has a default value of 100.

Remarks

This attribute cannot be used in conjunction with the fullScreen attribute.

If width and height are specified, and the resulting video window is larger than the video being played, the video can be enlarged by scaling up to the maximum size accommodated by the window. If width and height are not specified, zoom is limited to values of 100 or less.

If the shrinkToFit property is false, the video will change proportion upon zooming in order to fit itself to the available space. If shrinkToFit is true, the video will shrink to fit within the most restrictive dimension, while retaining its original proportions.

See Also

  • VIDEO Element
  • VIDEO.fullScreen
  • VIDEO.shrinkToFit


VIDEOSETTINGS Element

The VIDEOSETTINGS element provides a way to modify various video settings, using the attributes and method listed here.

The VIDEOSETTINGS element supports the following attributes.

Attribute | Description
brightness | Specifies or retrieves the brightness setting of the video.
contrast | Specifies or retrieves the contrast setting of the video.
hue | Specifies or retrieves the hue setting of the video.
saturation | Specifies or retrieves the saturation setting of the video.

The VIDEOSETTINGS element supports the following method.

Method | Description
reset | Resets all attributes to their default values.

The VIDEOSETTINGS element supports onchange event handlers.


VIDEOSETTINGS.brightness

The brightness attribute specifies or retrieves the brightness setting of the video.

Syntax

elementID.brightness

Possible Values

This attribute is a read/write Number (long) with a value ranging from –127 to +127 and a default value of 0.

See Also

  • VIDEOSETTINGS Element


VIDEOSETTINGS.contrast

The contrast attribute specifies or retrieves the contrast setting of the video.

Syntax

elementID.contrast

Possible Values

This attribute is a read/write Number (long) with a value ranging from -127 to +127 and a default value of 0.

See Also

  • VIDEOSETTINGS Element


VIDEOSETTINGS.hue

The hue attribute specifies or retrieves the hue setting of the video.

Syntax

elementID.hue

Possible Values

This attribute is a read/write Number (long) with a value ranging from -127 to +127 and a default value of 0.

See Also

  • VIDEOSETTINGS Element


VIDEOSETTINGS.saturation

The saturation attribute specifies or retrieves the saturation setting of the video.

Syntax

elementID.saturation

Possible Values

This attribute is a read/write Number (long) with a value ranging from -127 to +127 and a default value of 0.

See Also

  • VIDEOSETTINGS Element


VIDEOSETTINGS.reset

The reset method resets all attributes to their default values of zero.

Syntax

elementID.reset()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • VIDEOSETTINGS Element


VIEW Element

The VIEW element contains the user interface details of a skin, which use the following attributes, methods, and event handlers. Multiple VIEW elements can be defined within a THEME element to provide different interfaces for different situations. Note that each view has its own variable scope, which means it cannot share attribute values with other views.

The VIEW element supports the following attributes. Attributes marked with an asterisk (*) are also supported by the SUBVIEW element.

Attribute | Description
backgroundColor * | Specifies or retrieves the background color of the VIEW or SUBVIEW.
backgroundImage * | Specifies or retrieves the background image of the VIEW or SUBVIEW.
backgroundTiled * | Specifies or retrieves a value indicating whether the background image of the VIEW or SUBVIEW is tiled.
category | Specifies or retrieves the category for which the user interface will appear.
focusObjectID | Specifies or retrieves a value indicating which element has keyboard focus.
maxHeight | Specifies or retrieves the maximum height of the VIEW when resizing.
maxWidth | Specifies or retrieves the maximum width of the VIEW when resizing.
minHeight | Specifies or retrieves the minimum height of the VIEW when resizing.
minWidth | Specifies or retrieves the minimum width of the VIEW when resizing.
resizable | Specifies or retrieves a value indicating whether the VIEW can be resized.
scriptFile | Specifies the file names of accompanying JScript files.
timerInterval | Specifies or retrieves the interval, in milliseconds, at which the timer fires events to the ontimer event handler.
title | Specifies or retrieves the title of the VIEW.
titleBar | Specifies or retrieves a value indicating whether the window title bar is shown.
transparencyColor * | Specifies or retrieves the transparency color of the background image.

The VIEW element supports the following methods.

Method | Description
close | Closes the VIEW.
maximize | Maximizes the VIEW.
minimize | Minimizes the VIEW.
restore | Restores the VIEW.
returnToMediaCenter | Returns the user to the Media Center.
size | Resizes the VIEW on a specified edge.

The following event handlers can be implemented in the VIEW element.

Event handler | Description
onclose | Handles an event that occurs when the VIEW is about to be closed.
onerror | Handles an error event if Settings.enableErrorDialogs is set to false.
onload | Handles an event that occurs when the VIEW is first displayed.
ontimer | Handles timer events.

The ambient attributes and ambient events are also supported by this element, except where noted.


VIEW.backgroundColor

The backgroundColor attribute specifies or retrieves the background color of the VIEW or SUBVIEW.

Syntax

elementID.backgroundColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value or the value “none”. It has a default value of “white”.

See Also

  • VIEW Element
  • Color Reference


VIEW.backgroundImage

The backgroundImage attribute specifies or retrieves the background image of the VIEW or SUBVIEW.

Syntax

elementID.backgroundImage

Possible Values

This attribute is a read/write String.

Remarks

The supported formats are BMP, JPG, GIF, and PNG.

See Also

  • VIEW Element


VIEW.backgroundTiled

The backgroundTiled attribute specifies or retrieves a value indicating whether the background image of the VIEW or SUBVIEW is tiled.

Syntax

elementID.backgroundTiled

Possible Values

This attribute is a read/write Boolean.

Value | Description
true | The image is repeated horizontally and vertically.
false | Default. The image is not repeated.

See Also

  • VIEW Element


VIEW.category

The category attribute specifies or retrieves the category for which the user interface will appear.

Syntax

elementID.category

Possible Values

This attribute is a read/write String containing one of the following values.

Value | Description
All | Default. Theme for all types of media
Radio | The UI for Radio Playback
CD | The UI for CD playback
DVD | The UI for DVD playback
Music | The UI for MP3, WAV, MIDI, WMA
Video | The UI for Video playback

Remarks

The theme manager will detect what type of media is being played, load the theme file, and select the correct VIEW element based upon the category name.

See Also

  • VIEW Element


VIEW.close

The close method closes the VIEW.

Syntax

elementID.close()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

See Also

  • VIEW Element


VIEW.focusObjectID

The focusObjectID attribute specifies or retrieves a value indicating which element has keyboard focus.

Syntax

elementID.focusObjectID

Possible Values

This attribute is a read/write String specifying the id of the element that has focus. It has no default value.

Example

<VIEW
  backgroundImage=“greenstone.bmp”
  focusObjectID=“button2”
>
  <BUTTON id=“button1”/>
  <BUTTON id=“button2”/>
</VIEW>

See Also

  • VIEW Element


VIEW.maxHeight

The maxHeight attribute specifies or retrieves the maximum height of the VIEW when resizing.

Syntax

elementID.maxHeight

Possible Values

This attribute is a read/write Number with a value of zero or greater. It has a default value of zero, which means there is no restriction on the maximum height of the VIEW.

See Also

  • VIEW Element
  • 4VIEW.minHeight


VIEW.maximize

The maximize method maximizes the VIEW.

Syntax

elementID.maximize()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1”>
    <BUTTON id=“Open” Image=“Open.png”
        onclick=“jscript:View1.maximize()”>
    </BUTTON>
  </VIEW>
</THEME>

See Also

  • VIEW Element
  • VIEW.minimize


VIEW.maxWidth

The maxWidth attribute specifies or retrieves the maximum width of the VIEW when resizing.

Syntax

elementID.maxWidth

Possible Values

This attribute is a read/write Number with a value of zero or greater. It has a default value of zero, which means there is no restriction on the maximum width of the VIEW.

See Also

  • VIEW Element
  • VIEW.minWidth


VIEW.minHeight

The minHeight attribute specifies or retrieves the minimum height of the VIEW when resizing.

Syntax

elementID.minHeight

Possible Values

This attribute is a read/write Number with a value of zero or greater. It has a default value of zero, which means there is no restriction on the minimum height of the VIEW.

See Also

  • VIEW Element
  • VIEW.maxHeight


VIEW.minimize

The minimize method minimizes the VIEW.

Syntax

elementID.minimize()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1”>
    <BUTTON id=“Open” image=“Open.png”
        onclick=“jscript:View1.minimize()”>
    </BUTTON>
  </VIEW>
</THEME>

See Also

  • VIEW Element
  • VIEW.maximize


VIEW.minWidth

The minWidth attribute specifies or retrieves the minimum width of the VIEW when resizing.

Syntax

elementID.minWidth

Possible Values

This attribute is a read/write Number with a value of zero or greater. It has a default value of zero, which means there is no restriction on the minimum width of the VIEW.

See Also

  • VIEW Element
  • VIEW.maxWidth


VIEW.onclose

The onclose event handler handles an event that occurs when the VIEW is about to be closed.

Syntax

onclose

See Also

  • VIEW Element


VIEW.onerror

The onerror event handles an error event if Settings.enableErrorDialogs is set to false.

Syntax

onerror

See Also

  • VIEW Element


VIEW.onload

The onload event handler handles an event that occurs when the VIEW is first displayed.

Syntax

onload

See Also

  • VIEW Element


VIEW.ontimer

The ontimer event handles timer events.

Syntax

ontimer

Remarks

The timerInterval attribute specifies the interval at which timer events will be fired.

See Also

  • VIEW Element
  • VIEW.timerInterval


VIEW.resizable

The resizable attribute retrieves a value indicating whether the VIEW can be resized.

Syntax

elementID.resizable

Possible Values

This attribute is a read-only Boolean with a default value equal to the titlebar attribute.

Values | Description
true | Default. View can be resized.
false | View cannot be resized.

Remarks

If there is no titlebar, and therefore no window or border, you must use the size method to resize the VIEW element.

See Also

  • VIEW Element


VIEW.restore

The restore method restores the VIEW.

Syntax

elementID.restore()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1”>
    <BUTTON id=“Open” image=“Open.png”
        onclick=“jscript:View1.restore()”>
    </BUTTON>
  </VIEW>
</THEME>

See Also

  • VIEW Element


VIEW.returnToMediaCenter

The returnToMediaCenter method returns the user to the Media Center.

Syntax

elementID.returnToMediaCenter()

Parameters

This method takes no parameters.

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1” backgroundImage=“greenstone.bmp”>
    <BUTTON id=“Open” image=“Open.png”
        onclick=“jscript:View1.returnToMediaCenter()”>
    </BUTTON>
  </VIEW>
</THEME>

See Also

  • VIEW Element


VIEW.scriptFile

The scriptFile attribute specifies the file names of accompanying JScript files.

Syntax

elementID.scriptFile

Possible Values

This attribute is a write-only String with no default value. The file names of multiple JScript files are delimited with semicolons with no leading or following spaces.

Example

<VIEW id=“theView” scriptFile=“theScript.js”>
</VIEW>

Remarks

The code in the specified files can be used by any event handler in the View. Code that is used by event handlers in multiple Views can be placed in a file with the same name as the skin definition file but with a .js extension instead of a .wms extension. This file is loaded automatically and need not be specified in the skin definition file.

See Also

  • VIEW Element


VIEW.size

The size method resizes the VIEW on a specified edge.

Syntax

elementID.size(handle)

Parameters

handle

String specifying the edge or corner to move when sizing. This string must have one of the following eight values.

Edge | Corner
top | topright
right | bottomright
bottom | bottomleft
left | topleft

Return Values

This method does not return a value.

Example

<THEME>
  <VIEW id=“View1” backgroundImage=“greenstone.bmp”>
    <BUTTON id=“sizer” horizontalAlignment=“right”
        verticalAlignment=“bottom” image=“Open.png”
        onmousedown=“jscript:View1.size(‘bottomright’)”>
    </BUTTON>
  </VIEW>
</THEME>

Remarks

This method is typically called from within an onmousedown handler. It takes care of resizing while the mouse is dragged and stops resizing when the mouse button is released. If the size of the VIEW is restricted, you cannot drag the mouse to resize the View beyond the restricted bounds.

See Also

  • VIEW Element


VIEW.timerInterval

The timerInterval attribute specifies or retrieves the interval, in milliseconds, at which the timer fires events to the ontimer event handler.

Syntax

elementID.timerInterval

Possible Values

This attribute is a read/write Number with a default value of 1000.

Value | Description
0 | The timer event does not fire.
50 and above | The interval in milliseconds.

Any value below 50 (including negative numbers, but not including zero) generates an error and the previous value is maintained.

Remarks

This will not fire automatically if no ontimer event handler is implemented. Thus there is no performance degradation even though the default value is non-zero.

See Also

  • VIEW Element
  • VIEW.ontimer


VIEW.title

The title attribute specifies or retrieves the title of the VIEW.

Syntax

elementID.title

Possible Values

This attribute is a read/write String up to 255 characters long with no default value.

Remarks

The title specified or retrieved is the display name for the theme.

See Also

  • VIEW Element
  • VIEW.titleBar


VIEW.titleBar

The titleBar attribute retrieves a value indicating whether the window title bar is shown.

Syntax

elementID.titleBar

Possible Values

This attribute is a read-only Boolean.

Value | Description
true | Default. The window title bar is shown.
false | The window title bar is not shown.

Remarks

If the title bar is shown, the control box, minimize, and close buttons will be shown. The title of the window will be the title of the VIEW element.

If titleBar is set to true and the user attempts to change the value of Video.zoom, the change will not take place unless the skin monitors zoom and takes appropriate action to resize itself.

See Also

  • VIEW Element
  • VIEW.title
  • VIDEO.zoom


VIEW.transparencyColor

The transparencyColor attribute specifies or retrieves the transparency color of the background image.

Syntax

elementID.transparencyColor

Possible Values

This attribute is a read/write String containing any Microsoft Internet Explorer color value. It has no default value.

Because JPGs are lossy and therefore subject to unexpected color change, they are not recommended when transparencyColor is used.

See Also

  • VIEW Element
  • Color Reference


Miscellaneous

This section documents specialized attributes and other miscellaneous topics for use in creating skins.

The following topics are covered.

Topic | Description
Color Reference | A chart of colors, color names, and hexadecimal values for colors supported by skins.
Global Attributes | Global attributes are attributes that provide easy access to certain player elements or objects from anywhere within a skin.
Listening Attributes | Attributes used to connect one attribute to another so that its value changes every time the value of the other attribute changes.


Color Reference

The following colors are supported for use with skins. Every attribute that takes a color value can be specified using one of the following color names or hexadecimal values. Any six-digit hexadecimal number can be used, but only the ones on this chart have valid names.

Some attributes will also accept a value of “none”. For transparencyColor attributes, “none” means that no transparency is used. For other color attributes as appropriate, “none” means that transparency is used instead of a color.

aliceblue (#F0F8FF) | antiquewhite (#FAEBD7) | aqua (#00FFFF) | aquamarine (#7FFFD4)
azure (#F0FFFF) | beige (#F5F5DC) | bisque (#FFE4C4) | black (#000000)
blanchedalmond (#FFEBCD) | blue (#0000FF) | blueviolet (#8A2BE2) | brown (#A52A2A)
burlywood (#DEB887) | cadetblue (#5F9EA0) | chartreuse (#7FFF00) | chocolate (#D2691E)
coral (#FF7F50) | cornflowerblue (#6495ED) | cornsilk (#FFF8DC) | crimson (#DC143C)
cyan (#00FFFF) | darkblue (#00008B) | darkcyan (#008B8B) | darkgoldenrod (#B8860B)
darkgray (#A9A9A9) | darkgreen (#006400) | darkkhaki (#BDB76B) | darkmagenta (#8B008B)
darkolivegreen (#556B2F) | darkorange (#FF8C00) | darkorchid (#9932CC) | darkred (#8B0000)
darksalmon (#E9967A) | darkseagreen (#8FBC8B) | darkslateblue (#483D8B) | darkslategray (#2F4F4F)
darkturquoise (#00CED1) | darkviolet (#9400D3) | deeppink (#FF1493) | deepskyblue (#00BFFF)
dimgray (#696969) | dodgerblue (#1E90FF) | firebrick (#B22222) | floralwhite (#FFFAF0)
forestgreen (#228B22) | fuchsia (#FF00FF) | gainsboro (#DCDCDC) | ghostwhite (#F8F8FF)
gold (#FFD700) | goldenrod (#DAA520) | gray (#808080) | green (#008000)
greenyellow (#ADFF2F) | honeydew (#F0FFF0) | hotpink (#FF69B4) | indianred (#CD5C5C)
indigo (#4B0082) | ivory (#FFFFF0) | khaki (#F0E68C) | lavender (#E6E6FA)
lavenderblush (#FFF0F5) | lawngreen (#7CFC00) | lemonchiffon (#FFFACD) | lightblue (#ADD8E6)
lightcoral (#F08080) | lightcyan (#E0FFFF) | lightgoldenrodyellow (#FAFAD2) | lightgreen (#90EE90)
lightgrey (#D3D3D3) | lightpink (#FFB6C1) | lightsalmon (#FFA07A) | lightseagreen (#20B2AA)
lightskyblue (#87CEFA) | lightslategray (#778899) | lightsteelblue (#B0C4DE) | lightyellow (#FFFFE0)
lime (#00FF00) | limegreen (#32CD32) | linen (#FAF0E6) | magenta (#FF00FF)
maroon (#800000) | mediumaquamarine (#66CDAA) | mediumblue (#0000CD) | mediumorchid (#BA55D3)
mediumpurple (#9370DB) | mediumseagreen (#3CB371) | mediumslateblue (#7B68EE) | mediumspringgreen (#00FA9A)
mediumturquoise (#48D1CC) | mediumvioletred (#C71585) | midnightblue (#191970) | mintcream (#F5FFFA)
mistyrose (#FFE4E1) | moccasin (#FFE4B5) | navajowhite (#FFDEAD) | navy (#000080)
oldlace (#FDF5E6) | olive (#808000) | olivedrab (#6B8E23) | orange (#FFA500)
orangered (#FF4500) | orchid (#DA70D6) | palegoldenrod (#EEE8AA) | palegreen (#98FB98)
paleturquoise (#AFEEEE) | palevioletred (#DB7093) | papayawhip (#FFEFD5) | peachpuff (#FFDAB9)
peru (#CD853F) | pink (#FFC0CB) | plum (#DDA0DD) | powderblue (#B0E0E6)
purple (#800080) | red (#FF0000) | rosybrown (#BC8F8F) | royalblue (#4169E1)
saddlebrown (#8B4513) | salmon (#FA8072) | sandybrown (#F4A460) | seagreen (#2E8B57)
seashell (#FFF5EE) | sienna (#A0522D) | silver (#C0C0C0) | skyblue (#87CEEB)
slateblue (#6A5ACD) | slategray (#708090) | snow (#FFFAFA) | springgreen (#00FF7F)
steelblue (#4682B4) | tan (#D2B48C) | teal (#008080) | thistle (#D8BFD8)
tomato (#FF6347) | turquoise (#40E0D0) | violet (#EE82EE) | wheat (#F5DEB3)
white (#FFFFFF) | whitesmoke (#F5F5F5) | yellow (#FFFF00) | yellowgreen (#9ACD32)

For more information, see the Color Table article in MSDN Online.


Global Attributes

Global attributes are attributes that provide easy access to certain player elements or objects from anywhere within a skin.

The player global attribute is a reference to the Player object, and is used to access the primary functionality of Windows Media Player.

Example:

<BUTTON
  onclick="jscript:player.controls.play();"
/>

The theme global attribute is a reference to the THEME element. This is the proper way to access THEME attributes, rather than by specifying an ID within the THEME element.

Example:

<TEXT
  value="open"
  onclick="jscript:theme.openView('newView');"
/>

The view global attribute is a reference to the current VIEW. This can be used instead of the ID specified within the various VIEW elements.

Example:

<BUTTON
  id=”quitbutton”
  onclick=”jscript:view.close();”
/>

The event global attribute is used to access event attributes from within event handlers.

Example:

<BUTTON
  onclick=”jscript:if (event.altKey == true) myText.value=’ALT’;”
/>


Listening Attributes

A listening attribute is used to connect one attribute to another so that its value changes every time the value of the other attribute changes.

The listening attribute wmpprop: is the most useful. If the value of one attribute is specified to be the wmpprop: of a second attribute, the first value will be automatically updated to reflect the second value each time the second value changes.

Example:

<TEXT
  value="wmpprop:mySlider.value"
/>

In this way, the value of mySlider, shown by the position of the slider control, can also be shown as a number within a text box.

The two other listening attributes, wmpenabled: and wmpdisabled:, can be used to change the enabled attribute of a control depending on whether its functionality is currently available in the player. These attributes can listen only to methods of the Controls object.

Example:

<BUTTON
  id="play"
  enabled="wmpenabled:player.controls.play"
/>


Windows Media Player for Palm-size PC, Pocket PC, and Handheld PC Skin Development Kit

The Microsoft® Windows Media™ Player for Palm-size PC, Pocket PC, and Handheld PC Skin Development Kit provides detailed information on how to add skins to your Palm-size PC, Pocket PC, or Handheld PC. A skin is a customizable user interface that provides a unique look and feel for your Windows Media Player.


Introduction

Windows Media Player for Palm-size PC, Windows Media Player for Pocket PC, and Windows Media Player for Handheld PC all come with a default skin (user interface) that consists of various buttons and sliders that you can use to play, rewind, or stop the media content. If you would like to create your own skin, this document contains all the information you need.

The documentation is divided into three sections:

Section | Description
About Skins | Discusses the concepts needed to understand skin architecture and the rules you must follow to create a skin.
Skin Guide | Shows how to create a simple skin.
Skin Reference | Contains detailed references for all the parts of a skin.


Compatibility

Not every version of Windows Media Player for Palm-size PC, Pocket PC, and Handheld PC will work on every device. Some versions are pre-installed, some versions are available on the Microsoft Web site. Newer versions may offer skin features that earlier versions do not support.

The following table details compatibility for Windows Media Player for Palm-size PC, Pocket PC, and Handheld PC skins.

Software | Hardware | Availability | Skin features
Windows Media Player 1.0 | Pocket PC 3.0 devices: Casio Cassiopeia E-115/125, EM-500 Compaq Aero 15xx, Aero 21xx, iPAQ 3150, iPAQ 36xx HP Jornada 54x | Shipped with device | Audio only
Windows Media Player 1.1 | Palm-size PCs: Casio Cassiopeia E-10x class devices Compaq Aero 21xx, Aero 15xx HP Jornada 430 | Web release | Audio only
Windows Media Player 1.2 | Handheld PCs: HP Jornada 820, HP Jornada 680/690/720 Vadem Clio C-1050 Sharp Telios HC-VJ1c/HC-AJ2 NEC Mobile Pro 780/880devices | Web release (HPC 3.0), Shipped with device (HPC 3.1) | Audio only
Windows Media Player 7 | Pocket PC 3.0 devices: Casio Cassiopeia E-115/125, EG-800, EM-500 Compaq iPAQ 3150, iPAQ 36xx HP Jornada 54x | Web release | Local audio and video
Windows Media Player 7.1 | Pocket PC 3.0 devices: Casio Cassiopeia E-115/125, EG-800, EM-500 Compaq iPAQ 3150, iPAQ 36xx HP Jornada 54x | Web release | Streaming audio and video


About Skins

A skin is a customized user interface to Windows Media Player for Palm-size PC, Pocket PC and Handheld PC. You can create your own buttons to start and stop the media content, add sliders to change volume and position in the content, and provide the user with text information such as the name of a song. Best of all, you can add your own artwork or use clip art to create a unique look.

The basic steps in creating a skin are:

  1. Analyze what you want your user to do. What functions do you want to provide? You can do this in your head or on paper, but the important thing is to be aware of what you want the user of your skin to be able to do. You will want to examine what can be done to control the media, such as starting, stopping, and so on. You will probably want to go beyond the minimum functionality of PlayPause, Stop, Prev, Next, and Volume.
  2. Design your user interface. Decide which buttons, text and marquis boxes, and trackbars you want to provide to the user so that they can control the functions you chose in step 1. You may want to sketch out your ideas to see how they fit on the image size you will be working with.
  3. Create the art you want to show the user. This will consist of several images that show the background images, other images you may want to display, and mapping images if you use region buttons.
  4. Write the skin definition file that will link together the media functions, user interface, and images. You must follow certain rules for entering the text data into the file, but you can look at the default skin and use text templates to help align the information.

You do not need to follow these steps in the order given, but a good design will come from being aware of all the possibilities and taking care of all the details.


Windows Media Player Functionality

The following actions are available to the user of your skin:

  • Pushing buttons
  • Sliding trackbars
  • Reading text
  • Watching video


Button Types

You will want to provide the user with buttons to control the actions of the media content. Using the appropriate buttons, you can play, pause, or stop the content, move to different items in the playlist, mute the sound, or provide information about the content that is playing.

You do not need to provide all button types in your skin, but the best user experience will probably include the PlayPause, Stop, Prev, and Next button types.

The following button types are available:

  • Play
  • Pause
  • Stop
  • Prev
  • Next
  • Shuffle
  • Repeat
  • Mute
  • PlayPause
  • Info

For more information about button functions, see the Buttons section of the Skin Reference.


Trackbar Types

You do not need to include trackbars, also called sliders, but they can be very useful for letting the user adjust progress and the volume of the content. There are two types of trackbars:

  • Seek
  • Volume

For more information about sliders, see the Trackbars section of the Skin Reference.


Text Display Types

You do not need to include text displays in your skin, but there are many instances where you might want to. For example, you might want to include a Seek trackbar to allow the user to move to any position in the content, but you also might want to include a text display that shows the number of seconds that have elapsed since the content started playing. You might also want to display the name of the song or the current track number in the playlist.

Display Boxes

There are several types of text display boxes:

  • Time
  • Playlist
  • Track#
  • #Tracks
  • Title*
  • Author*
  • Copyright*
  • Filename
  • FilenameExt
  • Bitrate
  • Frequency

For more information about text display types, see the Text section of the Skin Reference.

*Title, Author, and Copyright should not be used in stand-alone text display boxes. You should display Title, Author, and Copyright information in a Marquis.

Scrolling Marquis

In addition to using the individual text display types, you can combine one or more types into a scrolling text marquis. This is useful if you want to display a grouping of related text information in a small area. For example, you might want to create a scrolling area that displays the playlist, the track number, and the number of tracks.

For more information about creating a text marquis, see the Marquis section of the Skin Reference.

Status display

Another type of text display is the status display. This lets you automatically display information about the current state of Windows Media Player. For example, the status display will inform the user when a media file is buffering so that it is evident that the Player is working. The following messages appear in the status display:

  • Buffering
  • Connecting
  • Paused
  • Playing
  • Ready
  • Stopped

No status display is available in skins for Windows Media Player prior to version 7.1. For compatibility details, see the Compatibility section.

For more information about creating a status display, see the Status section of the Skin Reference.


Video Display Types

There is one type of video display available in Windows Media Player for Pocket PC. You are not required to include a video display area in your skin, but if you are creating a skin for Windows Media Player 7 for Pocket PC or later, viewing video playback may be desirable. The video is displayed within a rectangular region, which is specified in the Video section of the skin definition file. No video display is available in skins for Windows Media Player prior to version 7. For compatibility details, see the Compatibility section.


User Interface Elements

Even though you can choose from a wide range of functionality for controlling the media content, playlists, and volume, it is up to you to provide the user of your skin with a way to interact with that functionality. What your user sees and taps on is called a user interface. For example, if you want the user to start the media content playing, you must provide a user-interface button element that will cause the content to play when the user taps the image of your button.

No elements are required, but if you do not have a few buttons to play and stop the content, not much will happen. And it is always nice to provide a volume control (unless you like your music loud all the time).

User interface elements correspond to types of functionality used to control the media content.

The following elements are provided:

Buttons

Many button types are provided. Buttons can be used to turn functions on or off, switch between two functions, or toggle a function between on and off.

Trackbars

You can provide linear control through trackbars. You will want to use trackbars to change the volume or the position in the media content.

Text

Text boxes can be used to display text to the user. A good use of a text box is to display the name of the song currently playing.

Marquis

A marquis is a scrolling text box that you can use to display text from more than one text category. For example, you can display the playlist, number of tracks, and track number playing. Use a marquis when you don't have much space and you have a lot to display.

Status

You can provide a status display that you can use to automatically display text messages that inform the user about the current state of Windows Media Player. For example, the status display will inform the user when a media file is buffering. No status display is available in skins for Windows Media Player prior to version 7.1. For compatibility details, please see the Compatibility section.

Video

You can provide a rectangular video display area in your skin if you want to show digital video files (.wmv). No video display is available in skins for Windows Media Player prior to version 7. For compatibility details, please see the Compatibility section.


Button Styles

Buttons come in two styles: coordinate-based and region-based. Each style provides three different kinds of buttons. For more details about buttons, see the Buttons section of the Skin Reference.

Coordinate Buttons

Coordinate buttons are placed on the screen by their coordinate definitions. There are three types of coordinate buttons:

Type | Description
Push | Button that triggers a single event.
Toggle | Button that changes state back and forth each time you tap on it. The two states are on and off. For example, the Repeat button changes from on to off when you tap it, and changes back to on when you tap it again.
2Push | Button that has two possible events to trigger. The first push triggers the first event, and the second push triggers a second event. The third push triggers the first event, and so on.

Region Buttons

Region buttons can be used to define what areas of a button will respond to taps. This lets you create buttons that are circular or otherwise not rectangular. The area that will respond to a tap is defined by areas in the Region bitmap that are filled with specific colors. For example, if the Region bitmap contains a blue circle, and you have defined blue as the color for your Prev button, then only taps inside the circle will trigger the Prev button. You must also define the coordinates of the button so that the secondary bitmaps such as Pushed and Disabled can be displayed in the correct location. The art in the Region bitmap is not seen by the user, but is used for hit processing only.

There are three types of region buttons:

Type | Description
PushHit | Same as Push but uses a Region bitmap to define the hit region.
ToggleHit | Same as Toggle but uses a Region bitmap to define the hit region.
2PushHit | Same as 2Push but uses a Region bitmap to define the hit region.


Trackbar Styles

Trackbars come in two styles: media position (seeking) and volume. They are created in the same way and have similar functions. For more details about trackbars, See the Trackbars section of the Skin Reference.

Media Position (Seek)

The Seek trackbar displays the current position of the current media content. The SeekThumb image changes location to match the media content position. For example, if the content is playing at the beginning of a track, the thumb image will be superimposed on the left end of the Seek trackbar image. If the content is nearly finished playing, the thumb image will be on the right side. The Seek thumb image moves horizontally.

The user can tap and drag on the Seek thumb image to change the current position within the content. For example, the user can tap and drag the thumb image to the center of the Seek trackbar, and the content will begin playing at the middle of the track.

Volume

The Volume trackbar displays the current volume that will be played through the speaker. The VolumeThumb image location matches the current volume level. For example, if the volume is all the way up, the thumb image will be superimposed on the right end of the Seek trackbar image. If the volume is turned all the way down, the thumb image will be on the left side. The Volume thumb image moves horizontally. The position of the Volume trackbar is not affected by the Mute button.

The user can tap and drag on the Volume thumb image to change the volume level. For example, the user can tap and drag the thumb image to the center of the Volume trackbar, and the sound output to the speaker will be 50 percent of full volume.


Text Styles

Text display boxes only come in one style: rectangular. You can vary the typeface, color, and alignment of any text box. For more details about Text display boxes, see the Text section of the Skin Reference.


Marquis Styles

Marquis display boxes only come in one style: rectangular. You can vary the typeface, color, and alignment of any text box. For more details about Marquis display boxes, see the Marquis section of the Skin Reference.


Status Styles

Status displays only come in one style: rectangular. You can vary the typeface, color, and alignment of the status display. No status display is available in skins for Windows Media Player prior to version 7.1. For compatibility details, please see the Compatibility section. For more details about status displays, see the Status section of the Skin Reference.


Video Styles

Video displays only come in one style: rectangular. You can vary the size and alignment of a video display. No video display is available in skins for Windows Media Player prior to version 7. For compatibility details, please see the Compatibility section. For more details about video display areas, see the Video section of the Skin Reference.


Art Files

You will need to create art files for your skin. There are several types of art files you can create, and they must be in a specific art file format.


Art File Types

There are seven types of art files you can create for your skin:

Art file | Description
Background | Required. The background is the image upon which all button images are superimposed
Disabled | Required. Images used to indicate that pushing buttons will have no effect.
Pushed | Required. Defines the images that are displayed when the user pushes buttons.
Region | Required. Defines bitmaps that use color areas to represent the tap-response locations for the hit-type buttons
Super | Required. Defines the Disabled images for trackbars.
SeekThumb | Defines an image to use in conjunction with a trackbar to indicate the current position in the media content.
VolumeThumb | Defines an image to use in conjunction with a trackbar to indicate the volume control position.

For more information about types of art files and how to identify them in the skin definition file, see the Bitmaps section of the Skin Reference.


Background File

Every skin needs a background file, which contains the image that the user will see when the skin is first displayed. This file is defined as the Background file in the skin definition file.

Here is a typical Background file:

This is the background image that users will see at first. However, they will also see the two thumb images at the appropriate locations on the trackbars for Seek (above) and Volume (below). In addition, any buttons that are disabled will be displayed using their Disabled images instead.


Button Feedback Files

Your skin can give the user feedback when a button is tapped by displaying an alternate image. For example, you can substitute a blue image for an orange image when the user taps on a particular button.

There are two types of button feedback files: Disabled and Pushed.

Disabled File

The Disabled file contains the images that will be displayed when a particular button function cannot be used or a button state is off. For example, if an empty playlist is defined, the Next and Prev buttons will be displayed, and they should be displayed using a disabled image. Also, for toggle buttons, Disabled is used to indicate that the state is off.

Here is a typical Disabled file:

This stores the images for hit-type buttons that are disabled. The images are similar to the Background file, but the colors are lighter. Using the offset defined in the Bitmaps section, the button images line up with the Background file image.

Notice that the background of the button image exactly matches the corresponding area in the Background file. This is important, because when a hit-type button is unavailable, the entire rectangle defined for the disabled image will replace the matching area in the Background file. Keep the graphic consistent with the background image to ensure that only the parts of the button that you want to appear different will actually change.

Pushed File

The Pushed file contains the images that will be displayed when the user taps on a button. You can also include the normal and pushed images for the pause state of the PlayPause button.

Here is a typical Pushed file:

This stores the images that will be displayed when the hit-type buttons are tapped. Also stored in this file are the normal and pushed images for the paused image of the PlayPause button. Except for the PlayPause secondary images on the right, the other button images line up with the Background image, using the offset defined in the Bitmaps section.

Notice that the background of the button image exactly matches the corresponding area in the Background file. This is important, because when the user taps a hit-type button, the entire rectangle defined for the pushed image will replace the matching area in the Background file. Keep the graphic consistent with the background image to ensure that only the parts of the button that you want to appear different will actually change.


Region Files

Region files are required if you use any type of hit button (2PushHit, PushHit, ToggleHit).

Region files are used to define areas that will respond to a tap, also known as a hit, on a specific button. For each hit button, an area in the Region bitmap is given a specific Web color (such as #FF0000, solid red). The color number is included in the region button definition, and the button is placed on the background using the coordinates of the area in the Region bitmap.

For example, draw a red circle in a location corresponding to the location of the Next button. Color it solid red (#FF0000). Then in the button definition, assign a Hit RGB value of 255,0,0 (which is the decimal equivalent of #FF0000). The Next button will only respond to taps (hits) inside the red circle.

Region buttons are used when you want to define complex shapes. You must still define the coordinates for each button so that secondary images such as Pushed and Disabled can be located correctly. Each button exists in a rectangle, and the rectangles must not overlap. Using hit buttons lets you define shapes that do not appear rectangular to the user.

Here is a typical Region file:

This file defines the parts of the screen for each hit-type button. Each color will be identified by its color number in the Buttons section of the skin definition file.


Super Files

Super files are used to store the Disabled images for trackbars. Because the main trackbar image is displayed in the Background file, and the user taps on the thumb image, not the trackbar image, only the Disabled image is needed for trackbars. It is stored in the file defined by Super in the Bitmaps section of the skin definition file. A Super file can also store the Pushed and Disabled images for other buttons such as Mute, which is not required to be a hit-type button.

Here is a typical Super file:

This stores the disabled images for the trackbars and the mute button. These images are offset as defined by the Bitmaps section.

The background area of the disabled trackbar image exactly matches the corresponding area in the Background file. This is important, because the entire rectangle defined for the disabled trackbar image will replace the matching area in the Background file. This ensures that the disabled trackbar image blends seamlessly into the background image.


Thumb Files

You need to create thumb images if you create a trackbar. There are two types: SeekThumb and VolumeThumb. They define the images that indicate the values of the media content position (seeking) and the volume. You can use one file and define it for use by both SeekThumb and VolumeThumb. Unlike the other art files, the thumb files are defined in the Trackbars section of the skin definition file.

Here is a typical SeekThumb file:

Here is a typical VolumeThumb file:

These two button files look the same but are slightly different sizes. The left image is the normal view that the user sees, and the right image is the Pushed image the user sees when they tap on the button.

You may want to make certain areas of the thumb images transparent. This will allow you to create thumb images in shapes other than rectangular. Any region of a thumb image that you fill with the color specified by the RGB value 255, 0, 255 will appear transparent in your skin.


Art File Formats

Art files for Palm-size PC skins and Pocket PC skins may be either bitmaps with the extension .bmp, or GIF images with the extension .gif. Only bitmaps are supported for Handheld PC skins. Do not include any spaces or commas in your art file name.

If you are synchronizing files to your Palm-size or Pocket PC, be sure that the synchronization does not change the extension or convert the image files to another format.

Many drawing programs can be used to create bitmaps and GIF files, or to convert art in other formats to bitmaps or GIF files. For example, you can use Microsoft Paint, which comes with Microsoft Windows, for simple drawings. For more elaborate drawings you might want to use a program such as Adobe Photoshop, which has hundreds of special effects you can apply to your drawings. You can even use Conduit's Pocket Artist to create images on your Palm-size PC!

You will want to trim the blank areas of your images around the edges to reduce file size. You can use the offsets in the Bitmaps section to compensate for removing blank spaces on the left and top sides. You can also trim the bottom and right blank edges of the images because they are not needed for measurements. The only files you should not trim are the Background, SeekThumb, and VolumeThumb images.


Color Palettes

Different devices have different color palettes. You will probably want to create different skins for each color palette. The following color palettes are recommended:

  • 16-bit
  • 8-bit
  • 2-bit grayscale


Image Sizes

You must take the display area size into consideration when creating artwork for skins.

Palm-size and Pocket PC Display Considerations

Windows Media Player for Palm-size PC features a 240x245 display area, while the Windows Media Player for Pocket PC features a 240x268 display area. If you want to work with both sizes, start with the smaller Palm-size PC display, and then simply add the extra 23 pixels to the bottom of the background to accommodate Pocket PCs. Depending on your layout, the same skin definition file and images can easily be used by both versions.

Handheld PC Display Considerations

If you are creating skins for a Handheld PC, you will need to create skins for the appropriate screen resolution. In addition to the default screen size, you must take into account the title bar and task bar and include a 26-pixel gutter at the bottom in case the task bar is set to autohide. Handheld PC skins use the following screen sizes:

Name (screen size) | Skin size with gutter | Active region size
HVGA (640x240) | 640x188 | 640x162
VGA (640x480) | 640x428 | 640x402
XVGA (800x480) | 800x428 | 800x402
SVGA (800x600) | 800x548 | 800x522

Note that the names (monikers) for Handheld PC screen sizes do not necessarily correspond to names for personal computer resolutions.


Button Placement

Even though you can draw buttons to be any shape, they are treated internally as having a rectangular outer boundary. For this reason, avoid overlapping button coordinates because unexpected results may occur.


Skin Definition File

The skin definition file is where you put all the pieces together. You define the images to use, specify the user interface elements you want the user to see, and type in the functions, coordinates, file names, and so on.


Creating a Skin Definition File

A skin definition file is a text file that defines a skin and all its composite parts. The file extension must be .skn.

Every skin definition file for the Palm-size, Handheld, or Pocket PC must start with a line that specifies the skin file version number. The following table shows Windows Media Player versions and the code line that should be used to identify each in a skin definition file. Although some of the numbers in the code lines are not what you would expect, they are correct as shown here. Copy them carefully.

Windows Media Player version | First line of skin definition file
1.0 1.1 | [Pocket WMP Skin File v1.0]
1.2 | [Pocket WMP Skin File v1.2]
7.0 | [Pocket WMP Skin File v2.0]
7.1 | [Pocket WMP Skin File v8.0]

The skin definition file consists of several sections. Each section defines a particular area of the skin. The sections must be placed in the following order:

  1. Bitmaps
  2. Video
  3. Buttons
  4. Status
  5. Text
  6. Marquis
  7. Trackbars

Each section starts with the name of the section in square brackets, for example:

[ Bitmaps ]

Then, one or more lines define individual images, buttons, and so on. For example, a Bitmaps section might include:

    Background  Background.bmp  0,0
    Disabled    Disabled.bmp    40,50
    Pushed      Pushed.bmp      40,50
    Region      Region.bmp      40,50
    Super       Super.bmp       0,0

It is not necessary to line up the values in columns, but it will help your code to be more readable. For more details about each section of the skin definition file, see the Skin Reference.

Note Do not use tabs anywhere in the file; use extra spaces instead. This is very important, because pressing the tab key while writing or editing your skin definition file will cause the entire skin to fail. Each line must be complete and cannot continue onto a second line.


Text Editors

You must use a text editor that does not include any formatting characters. A simple text editor such as Microsoft Notepad is recommended, though advanced editors such as the text editors in Microsoft Visual InterDev® or Microsoft Visual Studio® offer advanced features. You should not use an editor such as Microsoft Word because the default format saves extra formatting codes that will not be useable. If you use a word processor such as Word, you must remember to save as text every time you save your file.

You should probably turn off word wrap if your text editor allows it, and you may want to turn on the ability to view all characters to make sure you do not accidentally add any tabs or other control characters. Remember, including tab characters in your skin definition file will cause the skin to fail.


Rules for Each Line

Each definition in the skin definition file must be on a separate line. You must enter text in lines using the following rules:

  • Each line must end with a paragraph return. Some lines may be longer than the visible line length of your text editor, but do not break the lines. You may want to turn line wrap off to be sure your lines do not break.
  • Use only visible characters as defined in the Skin Reference.
  • A line consists of one or more items, separated by spaces.
  • You can enter as many spaces between items as you wish for readability.
  • Do not use any tab characters anywhere in the file.
  • Lines that begin with two consecutive forward slashes are ignored. Use these for comments. Blank lines are also ignored.


Required Elements

You must provide the following elements in your skin definition file:

  • Header. The main skin definition file header is required. For header version information, see the table in the Creating a Skin Definition File section.
  • Bitmaps section. The Bitmaps section is required. Additionally, the Bitmaps section must specify valid names for Background, Disabled, Pushed, Region, and Super image files.
  • Image files. You must provide Background, Disabled, Pushed, Region, and Super image files as part of your skin.

If you create a skin with only images defined, the skin will be visible but will not offer any meaningful functionality to the user. If you decide to create a skin without buttons, perhaps to prevent the user from skipping over certain content, be aware that it may still be possible to map functionality to the hardware buttons on the device.

Although Thumb files are not required, your trackbars will be difficult to use without thumbs.


Skin Guide

This section will show you how to create a simple skin. The following steps will be used:

  • Choosing the Functions
  • Designing the Interface
  • Creating the Art
  • Writing the Code


Choosing the Functions

The purpose of this skin is to provide basic functionality for playing audio. The following functions will be used:

PlayPause

Starting the media content is of prime importance. By choosing to work with PlayPause, you can get the added functionality of pausing.

Stop

You will want to add Stop to stop playing the content.

Next

If you have a playlist, you will want to be able to choose the next item. You need this for basic navigation of your media.

Prev

While you could use Next to cycle through the playlist until you came to the beginning, adding Prev will make it easy for the user to go backward as well as forward, when navigating the playlist.

Volume

You will want to provide the user with the ability to turn the volume up or down. A volume trackbar will be used.

Title and Author

The first five functions are recommended for every player. However, most users want to see the title and author of the current track. A marquis will be used to provide Title and Author information. Note that Title, Author, and Copyright are not recommended for use in Text boxes and that Marquis should be used for Author, Title and Copyright.


Designing the Interface

Once the functions have been chosen, the interface can be designed. A simple interface was chosen to match the functionality. Symbols for the controls were chosen from standard VCR controls.

Here is what the interface will look like:

PlayPause button

The user will be tapping this the most, so a larger button might be nice. The upper-right corner makes a good location that the user can find quickly. A solid arrow is used to indicate play and two vertical bars (not shown here) will be used to indicate pause.

Stop button

To make this easy to find, it is placed at the upper-left corner. A square is used to indicate stop.

Next and Prev buttons

Since these will not be used as often, they are placed on the left. The Next is above the Prev button because people will more likely want to move forward in a playlist. The double-arrow symbols are used because they are similar in function to a fast-forward control.

Volume trackbar

This is placed at the bottom of the screen and is a simple line with a thumb button on top of it.

Marquis text box

This is placed under the PlayPause button so that it is easy to see.

You may want to sketch this first and experiment with the placement of each user interface element. The design shown here was chosen for simplicity and ease of use.


Creating the Art

The art for this skin was created in Adobe Photoshop 5.5. Many other drawing programs could have been used, but Photoshop was chosen because it works particularly well with layers. Layers are helpful for creating multiple bitmap files that will line up with each other.

The following steps were used to create the art. Many other art procedures and tools can be used; this is just one way to do it. The important thing to keep in mind is that you want to end up with the specific bitmap files you need for your skin.


Make a Sketch

You do not need to do this, but it can be very helpful in getting your design to look the way you want it to. By planning ahead, you can save yourself having to move art around on multiple bitmap files.

Start up Photoshop with the image size required. Create a new layer to hold the rough sketch. If you have a sketch on paper, and a scanner, you might want to scan your sketch into Photoshop.

The PlayPause button is at the upper left, the Stop, Next, and Prev buttons are at the left, the Volume trackbar is at the bottom, and the Marquis is between the PlayPause button and the Volume trackbar.


Define the Rectangles

Because no user interface elements can overlap, it is useful to define the rectangles that each element will be drawn inside. Also, creating rectangles will be helpful when you have to write down the coordinates.

Turn on the Photoshop grid with grid lines every ten pixels. Turn on snap-to-grid to make rectangle drawing easy.

Create a new layer and draw rectangles. By having the sketch layer underneath, you know the general location where you want the user interface element to be, but you can now fine-tune the exact location. You can always change things later, but it will help to get as close as you can now.

Now that the rectangles are defined, you can turn off the sketch layer.


Creating the Background

Now you are ready to create the background image. Keep the rectangle layer visible, but keep it behind the layer you are drawing on, and use it as a guide to create the images for your skin. You will want to assemble each element in one or more layers to make it easy to copy over to another file later. For example, the PlayPause button will need to be copied to and recolored in the Paused file, the Disabled file, and the Region file. When you move art to the Region file, be sure that the art you copy does not have any complex edge effects such as shadows or bevels.

When you have finished creating the image you want, make visible all the layers you want to use and hide the other ones (such as sketch and rectangle). Then use the Save a Copy command to save the artwork to a .bmp file.

Here is the background image:

Bevels, embossing, and shadows were used to create the visual effects for the various elements. Note that there is no button for the volume thumb image. It will be created later.

Photoshop has several visual effects you can apply to images, making it easy to create more interesting artwork. For example, the PlayPause button was created with a simple circle. Then a bevel and emboss with shadow effect was created. The solid arrow was a simple triangle created with three clicks of the pen tool. The arrow was then given an embossed look by using an effect. When using a program like Photoshop, you do not have to be able to draw. You can just create simple images and apply effects. You can also import your own photos or scanned artwork.


Creating the Region file

You will want to create a Region file that shows what areas respond to taps. You can simply copy the base layers of each element to a new layer, and color them to correspond to the color numbers you will use in the skin definition file. Be sure that the images you create in this layer are solid and that no effects are applied. You will probably want to write down the color numbers for each image. You can get the color numbers from the Photoshop Color Picker. You want the RGB numbers, which are three decimal numbers. Each number ranges from 0 to 255. For example, a solid red would be 255, 0, 0.

Here is the Region file:

There are only four images in this file because only the PlayPause, Stop, Next, and Prev buttons are hit-type buttons.


Creating the Pushed file.

You can take the elements you created and reuse them to create the other images you need. By combining layers and coloring the results, you can create a Pushed bitmap that contains the images you want to be seen when the user pushes a button. This file also contains the secondary image for the paused state of the PlayPause button.

Here is the Pushed file:

The two buttons on the right are for the normal paused state and the pushed paused state of the PlayPause button. The color of the buttons is yellow, except for the normal paused state of the PlayPause button, as a good contrast to the green color used for the normal state of all buttons.


Disabled File

The Disabled file is similar to the Pushed file except that another color (red) is used to show when something is disabled.

Here is the Disabled file:

Note that files like this one could be trimmed on the right and bottom sides. The actual size of the bitmap is not important, only that the elements line up with the Region bitmap for hit testing, as measured from the top left corners (including offsets).


Super File

The Super file contains the disabled image for trackbars.

Here is the Super file:

It contains the image for a disabled Volume trackbar.


VolumeThumb File

The VolumeThumb file contains the thumb image that will be used with a Volume trackbar.

Here is the VolumeThumb file:

This contains the two thumb images. The one on the left is the normal state, and the one on the right is the pushed state. There is no disabled state. If a trackbar is disabled, the disabled background image of the trackbar is displayed from the Super file.


Writing the Code

You now have all the art files you need. All you need to do is write some simple commands in the skin definition file. For more information about the specifics of skin definition files, see the Skin Reference.


Initial Lines

Every skin definition file for the Palm-size, Handheld, or Pocket PC must start with a line that specifies the skin file version number. The following table shows Windows Media Player versions and the code line that should be used to identify each in a skin definition file. Although some of the numbers in the code lines are not what you would expect, they are correct as shown here. Copy them carefully.

Windows Media Player version | First line of skin definition file
1.0 1.1 | [Pocket WMP Skin File v1.0]
1.2 | [Pocket WMP Skin File v1.2]
7.0 | [Pocket WMP Skin File v2.0]
7.1 | [Pocket WMP Skin File v8.0]


Bitmaps Section

Next you must have a section that defines each of your bitmap files. Each type of bitmap you will use must have a file assigned to it, though you can have more than one type using the same bitmap.

[ Bitmaps ]

//  <Name>      <File name>     <X,Y>
//  ------      -----------     -----
    Background  Background.bmp  0,0
    Disabled    Disabled.bmp    0,0
    Pushed      Pushed.bmp      0,0
    Region      Region.bmp      0,0
    Super       Super.bmp       0,0

The bitmap section must begin with the word Bitmaps in brackets and then a line for each bitmap type you want to define. In this example, five types of bitmaps were defined. For more about the Bitmaps section, see Bitmaps in the Skin Reference.

Lines beginning with two forward slashes are not processed and can be used for comments or, as in the code above, a template to help you remember what goes in a section. You can also use templates to help you align everything into columns.


Buttons Section

Next you must define the buttons you will be using.

[ Buttons ]

//  <Function> <Type>     <Location>     <Push Image Src>  <Dis Image Src>    <Hit R,G,B>  <Norm 2 Image Src>  <Push 2 Image Src>
//  ---------- ------     ----------     ----------------  ---------------    -----------  ------------------  ------------------
    PlayPause  2PushHit   100,20,110,100 Pushed @ 100,20   Disabled @ 100,20    0,255,255  Pushed @ 270,20     Pushed @ 270,130
    Stop       PushHit    20,20,45,45    Pushed @ 20,20    Disabled @ 20,20   255,255,  0
    Next       PushHit    20,80,45,45    Pushed @ 20,80    Disabled @ 20,80   255,  0,  0
    Prev       PushHit    20,140,45,45   Pushed @ 20,140   Disabled @ 20,130    0,  0,255

There are four buttons defined in this section. The page you are viewing may wrap these lines, but when you type in the code, you must not wrap lines; that is, each line must be complete and end with a paragraph mark.

For each button you must define the function, type, location, pushed image source, disabled source, and color (for hit-type buttons). In addition, for the PlayPause button, you must define the normal and pushed image sources for the paused state.

For more about the Buttons section of the skin definition file, see Buttons in the Skin Reference.


Text Section

No text section is used in this skin, but you should include the heading for the section anyway.

[ Text ]

//  <Item>       <Location>     <Align>  <Font>          <Color>
//  ------       ----------     -------  ------          -------


Marquis Section

The Marquis section contains information about the marquis text box, which will display scrolling text.

[ Marquis ]

//  <Location>   <Font>       <Color>      <Text item combinations>
//  ----------   ------       -------      ------------------------
    100,150,100,20   Tahoma,12,N  255,0,0    Title+Author, Author, Title

This will display the Title and Author of the current content.

For more about the Marquis section, see Marquis in the Skin Reference.


Trackbars Section

The Trackbars section contains information about any trackbars you want to include.

[ Trackbars ]

// <Function>  <Location>     <Dis Image Src>  <Thumb Image Src>  <Thumb Size>
// ----------  ----------     ---------------  -----------------  ------------
   Volume      40,200,170,40  Super @ 15,10    VolumeThumb.bmp    23,22

Only the Volume trackbar is defined here. For more about the Trackbar section of the skin definition file, see Trackbars in the Skin Reference.


Installing Your Skin

The procedure for installing a skin is different for different versions of Windows Media Player. Skins that incorporate newer features, such as video, may produce unexpected results on older versions of Windows Media Player. Use one of the following procedures to install your skin:

  • To Install a Skin on Versions 1.0, 1.1, and Casio Mobile Audio Player
  • To Install a Skin on Version 1.2, or Versions 7.0 or 7.1 on a Pocket PC


To Install a Skin on Versions 1.0, 1.1, and Casio Mobile Audio Player

  1. Copy your skin files to a new folder on the device.
  2. Create a shortcut to your skin definition file.
  3. Copy that shortcut to the folder that contains Windows Media Player for Palm-size and Pocket PCs.
  4. Rename the shortcut to something short and simple to type.
  5. Start Windows Media Player for Palm-size and Pocket PCs.
  6. Using the keyboard, type in "skin=myskin", where myskin is the name of the shortcut to your skin. Tap on the ENTER key on the keyboard.
  7. Your skin will now be loaded.


To Install a Skin on Version 1.2, or Versions 7.0 or 7.1 on a Pocket PC

  1. Copy all your skin files to a new folder.
  2. Copy the folder containing your skin files to the Windows Media Player 7 folder on your Pocket PC device (the Windows Media Player folder on your Handheld PC).
  3. Start Windows Media Player 7 for Pocket PC or Windows Media Player for Handheld PC.
  4. Version 1.2: Click the Skin Chooser icon on the lower command bar of the Player.

    Version 7.0: Tap Tools and then Skin Chooser.

    Version 7.1: Tap Tools, then Settings, and then Skin Chooser.

    The Skin Chooser has two navigation buttons to allow you to scroll through the available skins, and will display a preview of each one. The name displayed for your skin will be the name of your skin definition file.

  5. Tap ok to select your skin.


Skin Reference

This reference is divided into the following sections.

Section | Description
Bitmaps | Detailed information about the art files used in skin creation.
Buttons | Detailed information about pushbutton controls available in skins.
Marquis | Information about using scrolling text boxes in skins.
Status | Information about including a status display in skins.
Text | Reference for using text boxes to display information in skins.
Trackbars | Reference for using sliding trackbar controls for volume and seek position.
Video | Information about including a video display area in skins for Pocket PC 3.0 devices.

Each section corresponds to a section of the skin definition file that you must fill in to use specific elements. The sections are listed here in alphabetical order. To learn the order in which they must appear in a skin definition file, see Creating a Skin Definition File. Details about the composition of the skin definition file are given in the About Skins section.


Bitmaps

You must use one or more images in your skin, and each image must be defined in the skin definition file. If you do not define an image in this section, your skin will not be able to use it.

The term "bitmap" is used throughout the reference in a generic sense, and refers to both bitmap images with a .bmp extension and GIF images with a .gif extension.

Note: Only bitmaps with a .bmp extension are supported by Windows Media Player for Handheld PC.

The Bitmaps section of the skin definition file begins with this line:

[ Bitmaps ]

You then must add one or more lines that contain information about each of the images in your skin.

A typical line might be:

    Background  Background.bmp  0,0

You can use the following template for the Bitmaps section of your skin definition file:

//  <Type>      <Filename>      <X,Y>
//  ------      -----------     -----

You must use the following order for bitmap information for each line in the Bitmap section. Each part of the line is required.

  1. Bitmap Type
  2. File Name
  3. Coordinates


Bitmap Type

The following values are valid for the bitmap type. Only the Background type is required; others are optional and relate to different possible uses of images.

Value | Description
Background | Required. The background is the image upon which all button images are superimposed. The base background image dimensions include the full width and height of the screen. This is also the file where images for the natural states of buttons and trackbars are displayed. (Pushed and disabled buttons are not part of this image.)
Disabled | Indicates that pushing the button will have no effect. This value defines an image that is displayed when specific player functionality is unavailable to the user. You must supply a Coordinates value to indicate the Top and Left corner position of this image relative to the Background image.
Pushed | Defines an image that is displayed when the user pushes a button. Use Pushed to give visual feedback to the user when he taps on a button. You must supply a Coordinates value to indicate the Top and Left corner position of this image relative to the Background image.
Region | Defines images that use rectangular color blocks to represent the tap-response area for the hit-type buttons: PushHit, ToggleHit, 2PushHit. If you are using the hit-type buttons, you must supply a region image. This image file uses specific Windows Palette colors for each control. The colors are defined by numbers representing the value of red, green, and blue for the region. This image is never seen by the user. You must also supply a Coordinates value to indicate the Top and Left corner position of this image relative to the Background image.
SeekThumb | Defines an image that you will use in conjunction with a trackbar to indicate the current position in the media content. For example, if a song is half finished playing, the SeekThumb image is displayed in the middle of the trackbar. By tapping and dragging the SeekThumb image, the user can restart the content at any position, which is called seeking. The image of the trackbar itself is defined in the Background image. The SeekThumb image is not included in the Bitmaps section of the skin definition file, but is specified as part of the trackbar definition in the TrackBars section.
Super | Defines the disabled image for a trackbar. It can also contain alternate images for the mute button.
VolumeThumb | Defines an image to use in conjunction with a trackbar to indicate the volume position. For example, if volume is at 50 percent, the VolumeThumb image will be displayed in the middle of the trackbar. By tapping and dragging the VolumeThumb image, the user can change the volume to any percent. The image of the trackbar itself is defined in the Background image. The VolumeThumb image is not included in the Bitmaps section of the skin definition file, but is specified as part of the trackbar definition in the TrackBars section.

Note that the file name and the file type are not necessarily the same. You can call the Pushed file anything you like, but it is still referred to in other places as Pushed. For example, in the Buttons section, you will have an item such as:

Pushed @ 50,60

but this refers to the type of the file, not the file name.


File Name

This is the file name of the image. The path should not be given, and the file should be in the skin directory. The extension of the file name should be .bmp or .gif.


Coordinates

This defines the x- and y-coordinates of the image relative to the background file. Two positive integers are required, separated by a comma. There are two types of coordinates you must use, depending on the type of image you are defining.

Bitmap type | Coordinate values
Background Super | 0,0
Disabled Push Region | The positions of the top and left corners of the image relative to the background image, in pixels.


Sample Bitmap Section

The following lines show a typical Bitmaps section of a skin definition file:

[ Bitmaps ]

//  <Type>      <File name>     <X,Y>
//  ------      -----------     -----
    Background  Background.bmp  0,0
    Disabled    Disabled.bmp    40,50
    Pushed      Pushed.bmp      40,50
    Region      Region.bmp      40,50
    Super       Super.bmp       0,0

This defines five bitmaps that are used to create a background image, images for disabled and pushed buttons, a region image for region buttons, and a super image for trackbars.


Buttons

You will want to use one or more buttons in your skin, and each button must be defined in the skin definition file. If you do not define a button in this section, your skin will not be able to use it.

The buttons section of the skin definition file begins with this line:

[ Buttons ]

You then must add one or more lines that contain information about each of the buttons in your skin

A typical line might be:

    PlayPause  2PushHit   84,99,67,67   Pushed @ 44,50    Disabled @ 44,50     0,255,255  Pushed @ 160,5      Pushed @ 160,98

Note that the above line may wrap when you are viewing this page, but that it should be typed as one line starting with "PlayPause" and ending with "Pushed @ 160,98".

You can use the following template for the button section of your skin definition file:

// <Function> <Type>     <Location>     <Push Image Src> <Dis Image Src>    <Hit R,G,B> <Norm 2 Image Src> <Push 2 Image Src>

// ---------- ------     ----------     ---------------- ---------------    ----------- ------------------ ------------------

Again note that the above two line may wrap when you are viewing this page, but that the first line should be typed as one line starting with "// <Function>" and ending with "<Push 2 Image Src>". The second line starts with "// ----------" and ends with "------------------"

Button information for each line in the button section must appear in the following order. Only the first six parts of the line are required. Secondary images are not included unless they are needed.

  1. Button Function
    2.

  2. Button Type
    3.

  3. Button Location
    4.

  4. Pushed Image Source
    5.

  5. Image Source for Disabled Button
    6.

  6. Hit RGB Color
    7.

  7. Normal Secondary Image Source
    8.

  8. Pushed Secondary Image Source
    9.


Button Function

The following values are valid for the button function. You do not need to define values for functions that you will not be using in your skin.

Value | Description
Play | Plays the current selection in the playlist.
Pause | Pauses the media content.
Stop | Stops the media content.
Prev | Moves to the previous item in the playlist.
Next | Moves to the next item in the playlist.
Shuffle | Shuffles the playlist randomly.
Repeat | Repeats the playlist indefinitely.
Mute | Silences the audio output.
PlayPause | Toggles between the Play state and the Pause state.
Info | Provides information about the content that is playing.


Button Type

Buttons come in two general types: location and region. Each general type has three specific types, making six button types in all.

Location Button Types

Location buttons use coordinates to define their locations relative to the background. The following values are valid for location button types. You do not need to define values for types you will not be using in your skin.

Value | Description
Push | Defines a button that triggers an event once. The button must be pushed each time to trigger further events. An example would be a button that moves to the next item in the playlist. The location of the button is defined by its coordinates.
Toggle | Defines a button that triggers an event that changes a state. The state remains until the button is pushed again. An example is a button that shuffles the playlist. Once the playlist is in a shuffled state, it will remain shuffled until the button is pushed again. The location of the button is defined by its coordinates.
2Push | Defines a button that triggers an event and then changes to a state that is ready to trigger a different event. The two states are toggled every time the button is pushed. An example is a button that uses the PlayPause function to toggle between playing and pausing the media content. When the button is pushed the first time, the primary Play state is triggered and a secondary image is displayed to indicate that a Pause event is triggerable. When the button is pushed again, the Pause state is triggered and the original image is displayed to indicate that a Play event can now be triggered. The location of the button is defined by its coordinates.

Region Button Types

Region buttons use color areas in the Region image to define where taps will be processed for a particular button. The following values are valid for region button types. You do not need to define values for types you will not be using in your skin.

Value | Description
PushHit | Similar to the Push button value except that the hit area of the button is defined by the color value in the Region image.
ToggleHit | Similar to the Toggle button value except that the hit area of the button is defined by the color value in the Region image.
2PushHit | Similar to the 2Push button value except that the hit area of the button is defined by the color value in the Region image.


Button Location

You must define a location for your button image. Just drawing a button on the background does not tell the skin where the buttons are. You must enter four positive integers separated by commas. The numbers define the position of the left side, the position of the top edge, the width, and height of a button, in pixels.

If you are using region buttons (PushHit, ToggleHit, and 2PushHit), you still must enter four numbers. The values are used to determine the locations for the secondary images such as Pushed and Disabled..


Pushed Image Source

You must define the source of the image you want to display when the user pushes a button. The image comes from the file you defined as Pushed in the Bitmaps section. You must enter the image type followed by a space and the "@" symbol and another space. You must then enter two positive integers that define the top and left coordinates (in pixels) of the image you want to use inside the Pushed image file. The location at which the image will be displayed comes from the coordinates defined for the button relative to the Background image; but the location it comes from is defined by the two numbers following "Pushed @" and is relative to the Pushed image you are reading the image from.

For example, to use an image from the Pushed image that is in the Pushed file at a top and left location of 50,60 pixels, use:

Pushed @ 50,60

You must define a Pushed bitmap. If you do not want to display a different image, you can define the Background bitmap as your Pushed bitmap with an offset of 0,0 and you must still enter:

Pushed @ 50,60

where 50,60 is the location of the button you are working with in the Pushed file (in this case, the same location as the button on the Background bitmap). However, it is highly recommended that you display a Pushed image for all buttons to give your user feedback, because it is not always clear whether a tap produces a result, especially if you have music playing and cannot hear the tap or have the tapping sound turned off.


Image Source for Disabled Button

You must define the source of the image you want to display when a button is disabled or has a state that corresponds to off. The image comes from the file you defined as Disabled in the Bitmaps section. You must enter the image type followed by a space and the "@" symbol and another space. You must then enter two positive integers that define the top and left coordinates (in pixels) of the image you want to use inside the bitmap file. The location at which the image will be displayed comes from the coordinates defined for the button relative to the Background image; but the location it comes from is defined by the two numbers following "Disabled @" and is relative to the Disabled bitmap you are reading the image from.

For example, to use an image from the Disabled bitmap that is in the Disabled file at a top and left location of 50,60 pixels, use:

Disabled @ 50,60

You must define a Disabled bitmap. If you do not want to display a different image, you can define the Background bitmap as your Disabled bitmap with an offset of 0,0 and you must still enter:

Disabled @ 50,60

where 50,60 is the location of the button you are working with in the Disabled file (in this case, the same location as the button on the Background bitmap). However, it is highly recommended that you display a Disabled image for all buttons to give your users feedback, because many buttons will not be useable under certain conditions, such as an empty playlist. If users know a button is disabled, they will not keep trying to click on it or think your skin is broken!


Hit RGB Color

If you are using region buttons (PushHit, ToggleHit, and 2PushHit), you must define the color that the region image will use to determine the tap (hit) area of your button. The value must be three positive integers separated by commas. The values represent the amount of red, green, and blue for a bitmap color, and range from 0 to 255.

You can use any colors for the values, but be sure that each region button you define has a unique color in the Region image file and that the color value you define here as a number matches the actual color used in the Region image.

Some typical colors you might want to use include:

Value | Description
0,0,0 | Black (the absence of any color)
255,255,255 | White (the combination of all colors)
255,0,0 | Pure Red (no green or blue)
0,255,0 | Pure Green (no red or blue)
0,0,255 | Pure Blue (no red or green)

If you do not use region buttons, you must enter:

0,0,0


Normal Secondary Image Source

If you are using a 2Push or 2PushHit button, you must define the location of the normal image for the secondary state of the button. This will be the image users see when they push a PlayPause function button the first time.

To define this image, you must enter the image type followed by a space and the "@" symbol and another space. You must then enter two positive integers that define the top and left coordinates (in pixels) of the image you want to use inside the bitmap type you are drawing from.

For example, to define the normal image for a secondary image source, if your image is inside the Pushed bitmap, type:

Pushed @ 160,5

Secondary states cannot have a disabled image. Secondary images are assumed to be the same width and height as the primary image.


Pushed Secondary Image Source

If you are using a 2Push or 2PushHit button, you must define the location of the pushed image for the secondary state of the button. This will be the image users see when they push a PlayPause function button the second time.

To define this image, you must enter the image type followed by a space and the "@" symbol and another space. You must then enter two positive integers that define the top and left coordinates (in pixels) of the image you want to use inside the image type you are drawing from.

For example, to define the pushed image for a secondary image source, if your image is inside the Pushed bitmap, type:

Pushed @ 160,98

Secondary states cannot have a disabled image. Secondary images are assumed to be the same width and height as the primary image.


Sample Button Section

The following lines show a typical button section of a skin definition file:

[ Buttons ]

//  <Function> <Type>     <Location>     <Push Image Src>  <Dis Image Src>    <Hit R,G,B>  <Norm 2 Image Src>  <Push 2 Image Src>
//  ---------- ------     ----------     ----------------  ---------------    -----------  ------------------  ------------------
    PlayPause  2PushHit   84,99,67,67   Pushed @ 44,50    Disabled @ 44,50     0,255,255  Pushed @ 160,5      Pushed @ 160,98
    Info       PushHit    97,49,43,43    Pushed @ 57,0     Disabled @ 57,0      0,  0,  0
    Stop       PushHit    97,173,43,43   Pushed @ 57,124   Disabled @ 57,124  255,255,  0
    Prev       PushHit    40,83,43,43    Pushed @ 0,34     Disabled @ 0,34      0,  0,255
    Next       PushHit    153,83,43,43   Pushed @ 113,34   Disabled @ 113,34  255,  0,  0
    Shuffle    ToggleHit  40,136,43,43   Pushed @ 0,87     Disabled @ 0,87      0,255,  0
    Repeat     ToggleHit  153,136,43,43  Pushed @ 113,87   Disabled @ 113,87  255,  0,255
    Mute       Toggle     5,220,24,23    Super @ 247,29    Super @ 4,28         0,  0,  0

Note that the line length of this code may wrap on the screen or printed page, but you should only see 10 lines of code: two lines of column headings and definitions for 8 buttons.

This code defines eight buttons that are used to play, pause, and stop the media content; shuffle, repeat, and move through the playlist; and mute the volume. All the buttons except the mute button are region buttons. The mute button gets its pushed and disabled images from the Super bitmap for convenience.


Marquis

A marquis is a scrolling text display box that displays information from one or more text display boxes. You do not need to add a marquis, but it can be very useful when you have detailed information you want to display to the user in a limited space.

The text in the marquis will scroll only if both of the following conditions are met:

  • You have more text to display in the marquis than the width of the marquis display box.
  • The media content is either stopped or paused.

The marquis section of the skin definition file must begin with this line:

[ Marquis ]

You then must add one or more lines that contain information about each of the marquis display boxes in your skin.

A typical line might be:

    3,2,234,20   Tahoma,12,N  255,0,0    Playlist, Time, Filename

You can use the following template for the marquis section of your skin definition file:

//  <Location>   <Font>       <Color>      <Text item combinations>
//  ----------   ------       -------      ------------------------

You must use the following order for information in each line of the marquis section. Each part of the line is required:

  1. Marquis Location
  2. Marquis Font
  3. Marquis Color
  4. Text Combinations


Marquis Location

You must define the location of the marquis display box you wish to use. You must enter four positive integers, separated by commas, that define the left, top, width, and height of the text display box, in pixels, relative to the background image.

A typical value is:

180,46,50,30


Marquis Font

You must define the font used by the marquis display box you wish to use. The font is defined by three values, separated by commas, representing the face, size, and weight of the font.

Typeface Values

Any typeface name can be used if it is likely to be installed on the user's machine. If a typeface is not found on the machine, an alternate will be selected by the operating system. The following typefaces are usually found on Palm-size and Pocket PC machines:

Typeface | Description
Tahoma | A sans-serif typeface that is easy to read.
Lucida Console | A square-serif typeface that resembles the letters on a typewriter.


Marquis Color

The color value of the type must be specified. The value must be three positive integers separated by commas. The values represent the amount of red, green, and blue for a bitmap color, and range from 0 to 255.


Text Combinations

This value is a list of text display box combinations, separated by commas. Text display boxes can be joined together by a plus character to create a new marquis display value.

When determining what to display, Windows Media Player evaluates each item in the list to see if all parts are available. If not, the next item is evaluated, and so on, until all the available parts have been found.. For example, if you want to display Author and Title, but you're not sure whether both are available, use the following value:

Author+Title, Author, Title

The Author+Title will be displayed if the author and title have been defined for the content. If both are not defined, the Title is evaluated and displayed if defined. If the Title is not defined, the Author is displayed if defined. If neither is defined, then nothing is displayed.

Note that you should use Author, Title, and Copyright only in Marquis display boxes, not in Text display boxes.

When using the plus sign for concatenation, be sure you have no spaces on either side of the plus sign.


Sample Marquis Section

The following lines show a typical marquis section of a skin definition file:

//  <Location>   <Font>       <Color>      <Text item combinations>

//  ----------   ------       -------      ------------------------

    3,2,234,20   Tahoma,12,N  255,0,0    Title+Author, Title, Author

This defines a marquis display box that shows the title and author if both are defined, title if only title is defined, or author if only author is defined. If neither is defined, nothing will be displayed.


Status

You may want to use a status display in your skin. The status display must be defined in the skin definition file.

The status section of the skin definition file begins with this line:

[ Status ]

You then must add one more lines that contain information about the status display in your skin.

A typical line might be:

    On           45,193,120,13    Left    Tahoma,8,B        0,255,  0

You can use the following template for the status section of your skin definition file:

//  <Item>       <Location>     <Align>  <Font>          <Color>
//  ------       ----------     -------  ------          -------

You must use the following order for status display information for each line in the status section. Each part of the line is required.

  1. Item
  2. Location
  3. Align
  4. Font
  5. Color


Status Item

You must define the status item to contain the value "On". No other values are supported for the status item.


Status Location

You must define the location of the status display you wish to use. You must enter four positive integers, separated by commas, that define the left, top, width, and height of the status display, in pixels, relative to the background image.

A typical value is:

45,193,120,13


Status Alignment

You must define the alignment of the status display you wish to use. The following values are valid.

Value | Description
Left | The text is flush left, that is, lined up with the left margin of the status display.
Center | The text is centered in the status display.
Right | The text is flush right, that is, lined up with the right margin of the status display.


Status Font

You must define the font used by the status display you wish to use. The font is defined by three values, separated by commas, representing the face, size, and weight of the font.

Typeface Values

Any typeface name can be used if it is likely to be installed on the user's machine. If a typeface is not found on the machine, an alternate will be selected by the operating system. The following typefaces are usually found on Palm-size and Pocket PC machines:

Typeface | Description
Tahoma | A sans-serif typeface that is easy to read.
Lucida Console | A square-serif typeface that resembles the letters on a typewriter.

Size Values

This is the size of the typeface in points. Any positive integer value is valid, though numbers between 10 and 18 are recommended. Sizes smaller than 10 may be too hard to read and sizes above 18 may not give you enough space to display more than a few letters at a time.

Weight Values

The only values allowed are:

Value | Description
B | Bold type
N | Normal type


Status Color

The color value of the status display text must be specified. The value must be three positive integers separated by commas. The values represent the amount of red, green, and blue for a text color, and range from 0 to 255.


Sample Status Section

The following lines show a typical status section of a skin definition file:

//  <Item>       <Location>     <Align>  <Font>          <Color>

//  ------       ----------     -------  ------          -------

    On           50,200,125,16    Right    Tahoma,10,B        255,255,0


Text

You may want to use one or more text display boxes in your skin. Each text display box you use must be defined in the skin definition file. If you do not define a text display box in this section, your skin will not be able to use it.

The text section of the skin definition file begins with this line:

[ Text ]

You then must add one or more lines that contain information about each of the text display boxes in your skin

A typical line might be:

    Time         180,46,50,30   Right    Tahoma,16,N     255,255,255

You can use the following template for the text section of your skin definition file:

// <Type>       <Location>     <Align> <Font>          <Color>

// ------       ----------     ------- ------          -------

You must use the following order for text display box information for each line in the text section. Each part of the line is required.

  1. Type
    2.

  2. Location
    3.

  3. Align
    4.

  4. Font
    5.

  5. Color
    6.


Text Type

You must define the type of text display box you wish to use. The following types are valid:

Type | Description
Time | Current position of the media content in minutes and seconds.
Playlist | Name of the current playlist.
Track# | Current playlist item number.
#Tracks | Number of items in the current playlist.
Title | Title of the current item in the current playlist. Under certain conditions, this type may not display properly. You may want to avoid using this type. You may work around this problem by using Title as part of a Marquis.
Author | Author of the current item in the current playlist. Under certain conditions, this type may not display properly. You may want to avoid using this type. You may work around this problem by using Author as part of a Marquis.
Copyright | Copyright data of the current item in the current playlist. Under certain conditions, this type may not display properly. You may want to avoid using this type. You may work around this problem by using Copyright as part of a Marquis.
Filename | File name of the current item in the current playlist.
FilenameExt | The file name extension of the current item in the current playlist. The only supported values are wma and wav.
Bitrate | The encoded bit rate (in kbs) of the current content.
Frequency | The sampled frequency (in kHz) of the current content.


Text Location

You must define the location of the text display box you wish to use. You must enter four positive integers, separated by commas, that define the left, top, width, and height of the text display box, in pixels, relative to the background image.

A typical value is:

180,46,50,30


Text Alignment

You must define the alignment of the text display box you wish to use. The following values are valid:

Value | Description
Left | The text is flush left, that is, lined up with the left margin of the text box.
Center | The text is centered in the text box.
Right | The text is flush right, that is, lined up with the right margin of the text box.


Text Font

You must define the font used by the text display box you wish to use. The font is defined by three values, separated by commas, representing the face, size, and weight of the font.

Typeface Values

Any typeface name can be used if it is likely to be installed on the user's machine. If a typeface is not found on the machine, an alternate will be selected by the operating system. The following typefaces are usually found on Palm-size and Pocket PC machines:

Typeface | Description
Tahoma | A sans-serif typeface that is easy to read.
Lucida Console | A square-serif typeface that resembles the letters on a typewriter.

Size Values

This is the size of the typeface in points. Any positive integer value is valid, though numbers between 10 and 18 are recommended. Sizes smaller than 10 may be too hard to read and sizes above 18 may not give you enough space to display more than a few letters at a time.

Weight Values

The only values allowed are:

Value | Description
B | Bold type
N | Normal type


Text Color

The color value of the type must be specified. The value must be three positive integers separated by commas. The values represent the amount of red, green, and blue for a bitmap color, and range from 0 to 255.


Sample Text Section

The following lines show a typical text section of a skin definition file:

//  <Type>       <Location>     <Align>  <Font>          <Color>

//  ------       ----------     -------  ------          -------

    Time         180,46,50,30   Right    Tahoma,16,N     255,255,255

    Playlist     3,46,175,20    Left     Tahoma,10,N     255,255,255

    Track#       10,68,40,20    Left     Tahoma,14,N     255,255,255

This defines three text display boxes that show the current time within the content, the current playlist, and the current track number.


Trackbars

A trackbar displays an image that changes in small increments. Trackbars are used for volume controls and content position controls. You can use trackbars to display information about the content or allow the user to change the media information. For example, you can use a trackbar to let the user adjust the volume, and another trackbar that can show the user the current position of the content. Trackbars have a thumb image that defines the current setting of the trackbar value.

The trackbars section of the skin definition file must begin with this line:

[ Trackbars ]

You then must add one or more lines that contain information about each of the trackbars in your skin

A typical line is:

   Seek        5,25,226,17    Super @ 4,1      SeekThumb.bmp      18,17
   Volume      32,220,172,23  Super @ 32,27    VolumeThumb.bmp    23,22

You can use the following template for the trackbars section of your skin definition file:

// <Type> <Location>     <Dis Image Src> <Thumb Image Src> <Thumb Size>

// ---------- ----------     --------------- ----------------- ------------

You must use the following order for trackbar information for each line in the trackbar section. Each part of the line is required.

  1. Trackbar Type
  2. Trackbar Location
  3. Image Source for Disabled Trackbar
  4. Thumb Image Source
  5. Thumb Size


Trackbar Type

You must define the type of trackbar you want to use. The following types are valid:

Type | Description
Seek | Controls the value of the media content position. If the value is zero, the content is at the begining. The value increases positively until the content length is encountered. The user can slide the thumb image to change the value, and as the content plays, the thumb image will move to match the content position.
Volume | Controls the volume of the content as it is played. The value varies from 0 to 100. The user can slide the thumb image to change the volume. If the volume changes, the thumb image will move to match the new volume.


Trackbar Location

You must define the location of the trackbar you wish to use. You must enter four positive integer numbers, separated by commas, that define the left, top, width, and height of the trackbar, in pixels, relative to the background image.

A typical value is:

180,46,50,30


Image Source for Disabled Trackbar

You must define the source of the image you want to display when a trackbar is disabled, using the bitmap type you want to draw the image from. The image you display will usually be inside the Super file. You must enter the image type followed by a space and the "@" symbol and another space. You must then enter two positive integers that define the top and left coordinates (in pixels) of the image you want to use inside the bitmap type you are drawing from.

For example, to use an image from the Super bitmap that has a top and left position of 50,60 pixels, use:

Super @ 50,60

You must define an image location for a disabled trackbar image. If you do not want to display a new image, you can define the Background image as your Disabled image with an offset of 0,0 and you must still enter:

Super @ 50,60

where 50,60 is the location of the button you are working with in the Super file (in this case, the same location as the button on the Background bitmap). However, it is highly recommended that you display a Disabled image for all trackbars to give your user feedback, since trackbars will not be useable under certain conditions, such as Seek trackbars being disabled by an empty playlist. If they know a button is disabled, they won't keep trying to click on it or think your skin is broken!


Thumb Image Source

You must define the name of the file you want to draw images from when displaying the thumb image. This must be a valid file name with the extension .bmp or .gif. The file must contain two side-by-side images of identical size. They must be adjacent to each other with no space between. The top and left position of the left image must be at the top and left of the file. The image on the left side is the normal image for the thumb image, and the image on the right depicts the pushed state.

A typical value is:

thumb.bmp

You may want to make certain areas of the thumb image transparent. This will allow you to create thumb images in shapes other than rectangular. Any region of the thumb image that you fill with the color specified by the RGB value 255, 0, 255 will appear transparent in your skin.


Thumb Size

You must define the width and height of the thumb image in pixels. This is the size of the left image as defined in the Thumb Image Source part of the line.


Sample Trackbar Section

The following lines show a typical trackbar section of a skin definition file:

[ Trackbars ]

// <Type>      <Location>     <Dis Image Src>  <Thumb Image Src>  <Thumb Size>
// ----------  ----------     ---------------  -----------------  ------------
   Volume      32,220,172,23  Super @ 32,27    VolumeThumb.bmp    23,22

This defines a trackbar that allows the user to change the volume by tapping and dragging the volume thumb image.


Video

A video display allows the user to view digital video (.wmv) files. The video display area is only visible when a digital video file is playing or paused. When you design your skin, you will want to reserve space in the background image to contain the video display. If you don't, the video display may superimpose itself over any visible art, such as the background file, buttons, and trackbars, which will keep the user from operating the controls on your skin.

The video section of the skin definition file must begin with this line:

[ Video ]

You then must add a line that specifies the location and size of the video display area in your skin.

A typical line might be:

0,38,240,172

You can use the following template for the video section of your skin definition file:

// <Location>
// ----------


Video Location

You must define the location of the video display area in your skin. You must enter four positive integers, separated by commas, which define the left, top, width, and height of the video display, in pixels, relative to the background image.

A typical value is:

0,38,240,172


Video Image Source

There is no separate image required for the video display area. You might want to create an area in your background image, which will be displayed by default, to act as a placeholder. Make the area rectangular in shape, with the same width and height, in pixels, that you want to specify in your skin definition file. When a .wmv file plays, the video will be superimposed over that area in your background file.


Video Size

You can specify the size of the video display area up to the maximum size of the device display. However, such a large display area would cover all the controls your skin exposes, making them useless while video is playing. If the video display area is larger than the dimensions of the .wmv file playing, the digital video will be displayed at actual size and the unused portions of the video display will appear as a black border around the video image. If the video display area is smaller than the dimensions of the .wmv file playing, the digital video will still be displayed at actual size, but will appear centered and cropped within the available display area.

The recommended minimum size for the video display area is 160 x 112 pixels. The recommended standard size for the video display area is 208 x 160 pixels.


Sample Video Section

The following lines show a typical video section of a skin definition file:

[ Video ]

// <Location>
// ----------
0,38,208,160

This defines a video display area that allows the user to view digital video files (.wmv).


Windows Media Player Custom Visualizations

Microsoft® Windows Media™ Player provides visualizations that enable the user to see visual imagery that is synchronized to the sound of the media content as it plays. Several standard visualizations are included with Windows Media Player, including Spikes, Bars, and DotPlane. This section of the SDK provides programming information that will enable you to create your own visualizations.

The custom visualization documentation is divided into three sections:

Section | Description
About Custom Visualizations | Discusses the architecture of custom visualizations in abstract terms. You should read this section to understand how visualizations relate to Windows Media Player.
Custom Visualization Programming Guide | Explains what you need to do to create a custom visualization. This section contains useful hints and tips that will help you create interesting visualizations.
Custom Visualization Programming Reference | Provides a reference for the interface you must implement as well as other technical reference information.


About Custom Visualizations

Windows Media Player provides an interface to create custom visualizations. This section provides an overview of the architecture of visualizations, information about how they relate to Windows Media Player, and the technical details you will need to create custom visualizations.

Note that several places in the code, you will see the word Effect. Visualizations are effects.


User Overview

To the user, visualizations are images that dance in time to the music. They provide additional entertainment to enhance musical experiences. The more entertaining a visualization is, the better!

Here is what a typical visualization looks like:

Standard Visualizations

Windows Media Player includes several visualizations, such as:

Ambience

Plenoptic

Spike

Standard Presets

In addition, each visualization comes with specific presets that alter how the visualization is displayed. For example, the Spike visualization comes in two presets:

Spike

Amoeba

Both effects are part of the same visualization, but have different presets. A preset is a set of values for the attributes of a particular visualization.

Skin Attributes

If you create skins for Windows Media Player, you can display the standard visualizations in your skins using the Effects element. For more details on using visualizations in skins, see Windows Media Player Skins.


Developer Overview

From the developer's point of view, visualizations are software programs that take audio data provided by Windows Media Player and convert that data to graphics that will please the eye of the user. The main subjects a developer needs to understand in order to create a new visualization are:

Visualization Packaging

Visualizations are COM controls that Windows Media Player uses to turn audio waveforms into animated graphics in Microsoft Windows. The COM controls are packaged as Microsoft Windows DLLs (dynamically-linked libraries) and must be registered in the Windows registry. When Windows Media Player runs, registered custom visualizations are loaded and viewed in accordance with the instructions of the skin that Windows Media Player is using.

Audio Input

Windows Media Player provides your code with snapshots of audio frequency and waveform data at timed intervals measured in fractions of a second. The snapshot interval is internally determined by the Windows Media Player.

Graphical Output

The graphical output from your visualization is a Microsoft Windows device context. This is a standard Windows drawing surface that you can draw upon every time an audio snapshot is provided. All of the background Windows technology is taken care of for you. You just have to draw on the device context with the audio data provided.

Drawing Tools

You can draw on the device context with standard Microsoft Windows Graphics Device Interface (GDI) functions, using pens and brushes to create designs that are modified by the audio data supplied to you by Windows Media Player. GDI provides a rich set of drawing tools that can create many kinds of visual effects.

Programming Language

Microsoft Visual C++ 5.0 and higher is the only supported language for creating custom visualizations.

Custom Visualization Wizard

Windows Media Player provides a COM wizard that you can add to Visual C++ 6.0 that will generate the underlying code needed for your visualization. Not only are all source files provided, but a sample skin is generated to make it easy to test your visualization. The generated code creates a visualization similar to Bars, with two presets. You can then modify the code to create your own visualization. A registry file is also generated to register your visualization so that Windows Media Player can load it.


Flow of Control

Audio data comes into Windows Media Player continuously through a file or a stream. That data is passed to your visualization. You draw on a defined surface and pass that surface back to Windows Media Player. This interchange happens several times a second, and to the user, the result is a pleasing animation that moves in time to the music.

Here is the specific sequence of the visualization program flow:

  1. At a timed interval, Windows Media Player takes a snapshot of the audio that is playing.
  2. Windows Media Player supplies the data from that snapshot to your visualization through the Render function.
  3. You must write code that will run when Render is called. Your code draws on a window defined by Windows Media Player.
  4. In a window specified by the current skin, Windows Media Player displays what your code drew.
  5. This process repeats several times a second, creating graphical animations that are timed to the music. When the music stops playing, the visualization stops.


Building a Visualization

You must have three things to build a custom visualization:

  1. Microsoft Visual C++ 5.0 or later. This is the only compiler that is supported. Included with Visual C++ is the Microsoft Windows Platform SDK which will provide detailed instructions on using the Graphical Device Interface (GDI) drawing functions.
  2. The Windows Media Player SDK. Included with the SDK is the documentation you are reading right now, as well as the Windows Media Player Custom Visualization Wizard.
  3. Windows Media Player. You will not be able to test your custom visualization without it. It is also a great way to listen to music while you are coding!


Getting Started

To set up your development environment for creating custom visualizations, you must install the following items:

  • Microsoft Visual C++ 5.0 or higher
  • Windows Media Player 7.0
  • Windows Media Player SDK 7.0
  • Windows Media Player Custom Visualization Wizard

Installing Visual C++

Be sure you install Microsoft Visual C++ 5.0 or later. Follow the instructions that come with the compiler. Include the Platform SDK for 32-bit Windows because you will need specific information about the Graphics Display Interface (GDI) functions.

Installing Windows Media Player

Install version 7.0 or later of Windows Media Player. It will be needed to test your visualization.

Installing the Windows Media Player SDK

Besides reading the programming information, you will need the SDK to get the Windows Media Player Custom Visualization Wizard. Make sure that the SDK is at the same version level as Windows Media Player.

Installing the Wizard

Once you have installed the Windows Media Player SDK, you can find the Custom Visualization Wizard in this directory:

    \wizards\viz

The wizard file is named WMEffect.awx.

Copy the wizard to this directory on your hard drive:

    \Program Files\Microsoft Visual Studio\Common\MSDev98\Bin\IDE

You can also install it in this directory:

    \Program Files\Microsoft Visual Studio\Common\MSDev98\Template

If you installed Microsoft Visual Studio (which contains Microsoft Visual C++) in another directory, find the corresponding directory. If you are not sure where you installed it, you can search for other COM wizards with the awx extension.


Using the Wizard

Once you have installed the Custom Visualization Wizard, start up Microsoft Visual C++ , make a few choices, press the button, and you have all the code you need to get started.

Starting a New Project

Start up Visual C++. From the File menu, select New. If you have used Visual C++ before, you will notice that a new type of project is available to you, called "Microsoft Windows Media Player". Click once on "Windows Media Visualization Wizard" to select it. Do not click twice if you have not chosen a project name yet.

Give Your Project a Name

The name for your project will be the default name for the files you create and for the name of your visualization. You can always change the name later, but it will involve a lot of retyping. You cannot leave the name blank.

Press the Button

After you select Microsoft Windows Media Player as the type of project you want to create and give a name to the project, click on OK to get started.

Before your project is created, Visual C++ will show you a dialog box showing you what will be created. You will see that you will be creating a DLL for Win32 and you will be told what kinds of files will be created as source files. You will also see that your project will be placed in:

    \Program Files\Microsoft Visual Studio\MyProjects\projectname

where projectname is the name you gave to your project.

Click on OK in this dialog box, and the files will be generated.

Do a Test Build

From the Build menu, select Build projectname.dll, where projectname is the project name you chose. Your visualization will be built, and you can watch the progress of the build at the bottom of the screen.

Run Windows Media Player

Start a song in Windows Media Player and click through the visualizations. The presets that are automatically built for you are called projectname Bars and projectname Wave, where projectname is the name of your project.

Files the Wizard Generates

The following files are generated by the wizard. Note that projectname is the name of the project you chose when you ran the wizard.

effects.idl

The IDL (Interface Definition Language) file for all visualizations. This defines the IMWPMEffects interface. You will probably not want to change this file.

project.cpp

The main project file for your code. You will write your own implemention of Render here, as well as any other functions you need. If you add, subtract, or modify presets, you will want to change the code in Render, GetPresetTitle, and any other functions you implement.

projectdll.cpp

The code for setting up the DLL (dynamic-link library). You will probably not want to change this file.

projectdll.def

The definition file for the DLL. You will probably not want to change this file.

projectdll.rc

The resource file for the DLL. You may want to change this file if you add, subtract, or modify preset strings. If you need to add other resources, add them here.

iproject.idl

The IDL file for your project. You will probably not want to change this file.

StdAfx.cpp

The #include files for MFC (Microsoft Foundation Classes). You will probably not want to change this file.

project.h

The header file for your project. Declarations for your project go here. If you add, subtract, or modify presets, you will want to change this file. You can also add your own declarations here.

resource.h

The header file for resources. If you add, subtract, or modify presets, you will want to change this file.

StdAfx.h

The header file for MFC #include details. You will probably not want to change this file.

project.rgs

The registry file for your project. Use this to register your project in the Microsoft Windows Registry.

project.wms

A Windows Media Player skin definition file. You can use this to test your finished visualization.

basetsd.h

Definitions for data types. You probably do not want to modify this file.

effects.h

Header file for all visualizations. You probably do not want to modify this file.

iproject.h

Header file for the project IDL. Generated by the build.

iproject.tlb

Type Library (TLB) file for the project. Generated by the build.

iproject_i.

MIDL (Microsoft Interface Definition Language) file for your project. Generated by the build.


Implementing Your Code

Once you have completed the build process, you will probably want to improve upon the code generated by the wizard. Otherwise your visualization will look much like Bars. What you need to do is change the implementation of the Render function.


Implementing Render

The easiest way to think of visualization programming is that you are creating a handler for a timed event. At specific intervals, Windows Media Player takes a snapshot of the audio data it is playing, and provides the snapshot data to the currently loaded visualization. This is similar to event-driven programming and is part of the programming model of Microsoft Windows. You write code and wait for it to be called by a particular event.

Your code is an implementation the Effects::Render function, which contains the following parameters:

TimedLevel

This is a structure that defines the audio data your code will be analyzing. The structure is composed of two arrays. The first array is based on frequency information and contains a snapshot of the audio spectrum divided into 1024 portions. Each cell of the array contains a value from 0 to 255. The first cell starts at 20 Hz and the last at 22050 Hz. The array is two dimensional to represent stereo audio. The second array is based on waveform information and corresponds to audio power, where the stronger the wave is, the larger the value. The waveform array is a granular snapshot of the last 1024 slices of audio power taken at very small time intervals. This array also is two dimensional to represent stereo audio.

HDC

This is a Microsoft Windows handle to a device context. This gives a way to identify the drawing surface to Windows. You do not need to create it, you just need to use it for specific drawing function calls.

RECT

This is a Microsoft Windows rectangle that defines the size of a drawing surface. This is a simple rectangle with four properties: left, right, top, and bottom. The actual values are supplied by Windows Media Player so that you can determine how the user or skin developer has sized the window you will draw on. It also determines the position on the HDC that the effect is supposed to render on.


Using Timed Levels

The TimedLevel structure is composed of two two-dimensional arrays, a state value, and a time stamp value.

Frequency Array

The frequency array is a two-dimensional array. The first dimension of each array corresponds to the stereo audio channel (left or right), and the second corresponds to the frequency levels (in bytes) of the snapshot, where the audio spectrum is divided up into 1024 regions.

You can get the frequency array data supplied from the Windows Media Player in the following manner:

TimedLevel *pLevels;
int snapshot = pLevels->frequency[0][0];

The value of snapshot is for the left channel and contains the value of the lowest part of the frequency spectrum. For example, if snapshot has a large value, it indicates that the lowest 1024th part of the frequency spectrum is rich in frequency. A value of zero indicates no low frequency values in that part of the spectrum for the left channel. If you have a monophonic signal, only the first dimension has valid values.

If the signal is non-stereo, then the second array will contain a copy of the mono signal. That is, frequency[0][n] and frequency[1][n] will contain the same data, where n is the index into a particular cell.

Waveform Array

The waveform array is also a two-dimensional array. The first dimension of the array corresponds to the channel (left or right), and the second corresponds to the power levels (in bytes) of the snapshot, where the audio power is broken up into 1024 continguous time segments.

You can get the the waveform array data from Windows Media Player in the following manner:

TimedLevel *pLevels;
int snapshot = pLevels->waveform[0][0];

The value of snapshot is for the left channel and contains the first value of the quantized snapshot of the power values. When a snapshot is taken, it consists of 1024 tiny incremental measurements of the audio power. The lowest value of the array is generated by the first incremental measurement of audio power. Note that the values of the power are measured from -128 to +127 but the values in the array range from 0 to 255. If you have a monophonic wave, only the first dimension will have valid values.

If the signal is non-stereo, then the second array will contain a copy of the mono signal. That is, waveform[0][n] and waveform[1][n] will contain the same data, where n is the index into a particular cell.

State

The state variable reflects the audio playback state of Windows Media Player. The PlayerState enumeration values are

    stop_state              = 0,    // audio is currently stopped
    pause_state             = 1,    // audio is currently paused
    play_state              = 2     // audio is currently playing

You can use this variable to take different actions depending on the audio playback state. For example, you can play one kind of visualization when the audio is playing and another when it is stopped.

Time Stamp

The timeStamp variable reflects the current time when the snapshot is taken. This can be used to measure how frequently the snapshots are taken.

You can use this variable to time your animations. If the snapshots are too frequent, you can gracefully degrade your image to display in the manner you choose.


Using Device Contexts

The device context is a standard handle to a device context. You need this for many drawing functions so that Microsoft Windows knows which window to draw in. For example, to draw a rectangle, you need to specify the device context.

HDC hdc;
::Rectangle( hdc, 1, 1, 100, 100);

The device context is specified by Windows Media Player through the Render function. Use this device context for any drawing tool that requires a device context.


Using Rectangles

Rectangles are used to specify rectangular areas in Microsoft Windows. You can create many rectangles in your window, but Windows Media Player supplies the values of one rectangle through the Effects::Render function. This is called the prc rectangle, and it defines the rectangle that Windows Media Player will display your visualization through. Use this frequently to be sure you do not draw beyond the extents of the rectangle supplied by Windows Media Player.

A rectangle has four values that define it. They are left, top, right, and bottom. The top, left corner of the rectangle is defined by left and top, and the bottom, right corner of the rectangle is defined by bottom and right.

Use the following code to get the extents of your drawing rectangle. You need to do this because the user may resize the window, and you want to be sure that you are always drawing in an area the user can see.

int leftside = prc->left;
int rightside = prc->right;
int topside = prc->top;
int bottomside = prc->bottom;

For example, to draw from left to right, along the top of the window, use code like this:

::MoveToEx( hdc, prc->left, prc->top, NULL );
::LineTo(hdc, prc->right, prc->top);


Sample Render Code

Here is some sample code that uses the Render function to draw a line across the screen. The height of the line is defined by the waveform value.

STDMETHODIMP CStock::Render(TimedLevel *pLevels, HDC hdc, RECT *prc)
{
    // Create new brushes and pens.
    HBRUSH hNewBrush = ::CreateSolidBrush( 0 );
    // Create a new solid pen the color of the foreground.
    HPEN hNewPen = ::CreatePen( PS_SOLID, 0, m_clrForeground );

    // Add the pen to the device context.
    HPEN hOldPen= static_cast<HPEN>(::SelectObject( hdc, hNewPen ));

    // Fill the background with the black brush.
    ::FillRect( hdc, prc, hNewBrush );

    // Get the y value from the waveform.
    int y = pLevels->waveform[0][0];

    // Draw the line from left to right.
    ::MoveToEx( hdc, prc->left, y, NULL);
    ::LineTo(hdc, prc->right, y);

    // Delete your brush.
    if (hNewBrush)
    {
        ::DeleteObject( hNewBrush );
    }
    // Delete your pen.
    if (hNewPen)
    {
        ::SelectObject( hdc, hOldPen );
        ::DeleteObject( hNewPen );
    }

    // You're done for this round.
    return S_OK;
}

The Render function is where the main work of your code takes place. Every time Windows Media Player takes a snapshot of the audio, it will call this function and your code will run.

This code performs the following tasks. Refer to the Microsoft Windows Platform SDK for 32-bit Windows for more details about specific functions.

Creating Objects

Usually you will be using the drawing functions that come with the Microsoft Windows Graphical Display Interface (GDI). You need to create pens to draw lines and brushes to fill areas.

A solid black brush is created to fill in the background.

A solid pen is created to draw a line. The color will be the foreground color as defined by the skin that is going to display the visualization.

Adding the Object to the DC

You need to add the pen to the device context (DC). The DC is the portion of memory that all drawing data and objects are stored in. Essentially the DC is the window traffic manager that keeps track of everything graphical.

You need to cast the pen object you created and store it as an old pen. Use this coding technique for all new pens. This technique is required for 32-bit programming.

Filling in the Background

You now are ready to draw. The FillRect function will fill the rectangle of the window, as defined by the parameters of the Render function. The rectangle is filled with a black brush.

Getting Audio Data

Next the code gets some audio data from Windows Media Player. By using the waveform array, you can get the current value of the audio power at the moment the snapshot was taken. In this case, you are taking the audio data of the left channel. The first value in the array is the first 1024th of the audio power snapshot.

This information will be used to display a line whose height will match the audio power shapshot.

Draw the Line

The line is drawn from left to right using the MoveToEx and LineTo GDI functions.

First you move the pen to the starting point. In this case, x and y are used to define the left-to-right and top-to-bottom values the user will see on the screen. X is defined by the rectangle prc and specifically by the value of prc->left. Y is defined as the value of the waveform data at that moment.

Then you draw a line to the other side of the window. The point you draw the line to is again an x, y value. X is defined by the rectangle prc, but this time by prc->right. Y is still defined by the waveform data and is the same as the point you started from, because you are drawing a straight line from left to right.

Clean up Everything

You must delete the objects you create. Specifically you must delete any and all brushes and pens you create. It is good practice to delete pens and brushes as soon as you finish using them.

If you do not delete them before finishing your implementation of the Render function, your visualization will crash in a minute or less. You must keep a count of your pens and brushes and destroy every single one. Be especially careful not to create pens inside a code loop.

Use the coding technique given in the example to destroy your pens and brushes.

Important Destroy your pens and brushes!

When you have finished cleaning up, be sure to return S_OK so that Windows Media Player knows you are finished drawing. Once you finish, your drawing will be transferred to the window, another snapshot will be taken, Render will ask your code to draw again, and so on.


Implementing Other Functions

You will definitely want to write your own implementation of the Render function. Several other functions that are also member functions of the IWMPEffect interface are provided. Some will provide you with extra information that you can choose to use and others will automatically provide Windows Media Player with information that was generated by the wizard, such as the name of your visualization.

The IWMPEffect interface supports the following functions in addition to Render:

Function | Description
DisplayPropertyPage | Default implementation not supplied by wizard.
GetCapabilities | Gets the capabilities of your visualization and passes them to Windows Media Player.
GetCurrentPreset | The wizard created two presets when it generated the code for your visualization. This function is called when the skin developer wants to get the index of the current preset. You will not want to change the implementation of this function because it just uses information set by other functions.
GetPresetCount | The wizard created two presets when it generated the code for your visualization. You can change the count by changing the implementation of GetPresetCount. See Presets for more information about changing the presets.
GetPresetTitle | The wizard created two presets when it generated the code for your visualization. You can change the titles used by changing the implementation of GetPresetTitle. See Presets for more information about changing the presets.
GetTitle | Gets the title of your visualization and passes it to Windows Media Player. The wizard used the name of your project to generate the name that is passed back.
GoFullscreen | Default implementation not supplied by wizard.
MediaInfo | Retrieves the number of audio channels and the sample rate of the audio currently playing.
RenderFullScreen | Default implementation not supplied by wizard.
SetCurrentPreset | The wizard created two presets when it generated the code for your visualization. This function is called when the Windows Media Player wants to change to a named preset.


Presets

Presets are provided as a way to have different effects coming from the same visualization. For example, you could create a glow effect that was generated by one block of code, but use a preset to determine the color of the glow. Your preset names might be Red, Green, and Blue.

The wizard defines two presets for the code it generates. One is called Bars and the other is called Wave. The Bars preset displays bars that show the activity in the audio spectrum, and use the waveform data. The Wave preset displays a wiggling line that shows the audio power of the waveform.

If you change any of the preset information, you must also change the following parts of the generated code.

Render function

The IWMPEffects::Render function is in the file projectname.cpp, where projectname is the project name you chose when you ran the wizard.

The generated code in the Render function uses a switch statement to choose between two presets. The current preset is whatever the user selects in Windows Media Player. If you want to change which code runs for a particular preset or add or subtract a preset, modify the switch statement accordingly.

The two presets are defined by the PRESET_BARS and PRESET_SCOPE enumerations. The choice of which preset will be called is defined by m_nPreset.

GetPresetTitle

The IWMPEffects::GetPresetTitle function is in the file projectname.cpp, where projectname is the project name you chose when you ran the wizard.

The GetPresetTitle function sets up the relationships between the preset enumerations and the string resources. The enumerations PRESET_BARS and PRESET_SCOPE are generated by the wizard and are using the string resources IDS_BARSPRESETNAME and IDS_SCOPEPRESETNAME.

You need to change the enumerations and string resources if you add, subtract, or change presets.

Preset Enumerations

The preset enumeration is defined in the file projectname.h, where projectname is the project name you chose when you ran the wizard.

The enumeration defines the current two presets and the count. If you add or subtract presets or change the enumeration, be sure you change this enumeration so that the count and order of presets is correct. This enumeration is used to make sure that you call the correct preset in the Render function.

Resource Header

You must set the resources for names of your preset in the resource.h header file. The current presets are defined as:

#define IDS_BARSPRESETNAME              102
#define IDS_SCOPEPRESETNAME             103

If you add or subtract presets, you must change the resource header and the numbers for them.

Resource Strings

The actual names of the presets are defined in the resource file projectnamedll.rc, where projectname is the project name you chose when you ran the wizard. You can edit this file by hand or use the resource editor included with Microsoft Visual C++.

The names generated are the name of the visualization plus the specific preset. The resource file for the generated code will define them as:

    IDS_BARSPRESETNAME      "projectname Bars"
    IDS_SCOPEPRESETNAME     "projectname Wave"

where projectname is the name of the project name you chose when you ran the wizard. This is where you will change the actual names of the presets and this is how they will be referred to and displayed by Windows Media Player.


Installing Visualizations

You must provide an installation process for the user of your visualization. You must also provide an uninstall process for the user. The current version of Windows Media Player does not install visualizations from the user interface.

Installing to the Visualization Folder

It is recommended that you install all visualizations in the Visualizations subfolder of the folder where Windows Media Player is installed.

Registering Your Visualization

Visualizations are COM DLLs and follow all the normal rules of installation and deinstallation. You can use regsvr32.exe or other installation tools to register your visualization .


Submitting Your Visualization

If you want to submit your visualization to the Windows Media web site, do this:

Test Your Visualization

A test skin is provided by the wizard to test your visualization. In addition, you may want to try installing your visualization on several machines to be sure that everything works the way you want. Try every preset to make sure your code works correctly.

Sign Your Visualization

You must submit your visualization for code signing so that the user can decide whether or not to trust your visualization before they install it. You can get full details about code signing here.

Distributing Your Visualization

Consult the Windows Media Web Gallery for more information on how to distribute your visualization.


Custom Visualization Programming Guide

Writing your own visualization is as simple as implementing the Render function, modifying preset information, and building your DLL.


The Glow Sample

The following sample code creates a simple visualization called Glow. Three presets are used: Red, Green, and Blue. The Custom visualization wizard was run and the name Glow was chosen.

Glow simply changes color in time to the music. The glow flickers because the audio power of the waveform sometimes crosses zero at the moment of the snapshot. This sample is chosen because it is one of the simplest samples possible.


Implementing Render

The following code is used to implement the Render function:

STDMETHODIMP CGlow::Render(TimedLevel *pLevels, HDC hdc, RECT *prc)
{
    COLORREF mycolor;
    int mylevel = pLevels->waveform[0][0];

    switch (m_nPreset)
    {
    case PRESET_RED:
        {
        mycolor = RGB( mylevel, 0, 0);
        }
        break;
    case PRESET_GREEN:
        {
        mycolor = RGB( 0, mylevel, 0);
        }
        break;
    case PRESET_BLUE:
        {
        mycolor = RGB( 0, 0, mylevel);
        }
        break;
    }

     HBRUSH hNewBrush = ::CreateSolidBrush( mycolor );
    ::FillRect( hdc, prc, hNewBrush );

    if (hNewBrush)
    {
        ::DeleteObject( hNewBrush );
    }

    return S_OK;
}

Here is an explanation of the code:

A variable named mycolor is used for the color of the glow and is declared with COLORREF. All colors should use the COLORREF data type.

A variable named mylevel is used for the audio waveform level snapshot. This value will depend on the actual power level at the moment of the snapshot.

The switch statement is set by the preset that the user has chosen on Windows Media Player. The choice will set mycolor to the desired color (red, green, or blue). However, the exact color will be determined by the audio power level. For example, if the red preset is chosen, the color will be a solid red, but it will be lighter or darker depending on the audio waveform at the moment of the snapshot. Be sure to use the RBG macro to create your color.

A brush is created called hNewBrush, and it is used to fill the prc rectangle provided by Windows Media Player. The drawing surface is the hdc device context provided by Windows Media Player.

The brush is deleted by DeleteObject. Always be sure to delete any pens or brushes you create.

Once the Render code is finished, Windows Media Player will display the hdc graphics in a window determined by the skin being used.


Changing Presets

The following preset code sections were changed to allow three presets:

GetPresetTitle

This code was inserted in place of the generated preset code:

    switch (nPreset)
    {
    case PRESET_RED:
        bstrTemp.LoadString(IDS_REDPRESETNAME);
        break;

    case PRESET_GREEN:
        bstrTemp.LoadString(IDS_GREENPRESETNAME);
        break;

    case PRESET_BLUE:
        bstrTemp.LoadString(IDS_BLUEPRESETNAME);
        break;
    }

Enumerations

The following enumeration in Glow.h was changed to allow three presets:

enum {
    PRESET_RED = 0,
    PRESET_GREEN,
    PRESET_BLUE,
    PRESET_COUNT
};

Resource Header

The following resources were defined in Resource.h to allow three presets:

#define IDS_REDPRESETNAME               102
#define IDS_GREENPRESETNAME             103
#define IDS_BLUEPRESETNAME              104

Note that you must also change the resource number of _APS_NEXT_SYMED_VALUE to 106.

Resource File

The following strings must be changed in the Glowdll.rc file to allow three presets and give them names:

    IDS_REDPRESETNAME       "Glow Red"
    IDS_GREENPRESETNAME     "Glow Green"
    IDS_BLUEPRESETNAME      "Glow Blue"


Custom Visualization Programming Reference

The Custom Visualization Reference documents the following items.

Item | Description
Effects Interface | An interface to custom visualizations.
Visualization Structures and Enumeration Types | Data types for use in manipulating custom visualizations.


Effects Interface

In addition to the methods inherited from IUnknown, the Effects interface exposes the following methods, in IDL order.

Method | Description
Render | Renders the visualization
MediaInfo | Sends channel and sample-rate data to the visualization.
GetCapabilities | Gets the capabilities of the visualization.
GetTitle | Gets the display title of the visualization.
GetPresetTitle | Gets the title of the current preset.
GetPresetCount | Gets the preset count.
SetCurrentPreset | Sets the current preset by number.
GetCurrentPreset | Gets the current preset by number.
DisplayPropertyPage | Displays the property page of a visualization, if it exists.
GoFullscreen | Instructs the visualization to switch to full-screen mode.
RenderFullScreen | Renders the visualization in full-screen mode.


Effects::DisplayPropertyPage

The DisplayPropertyPage method displays the property page of a visualization, if it exists.

Syntax

HRESULT DisplayPropertyPage(
  [in] HWND hwndOwner
);

Parameters

hwndOwner

[in] Handle to the dialog that will be displayed.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

Implement this method if you want to display a property page to the user to adjust any values of the visualization.

See Also

  • Effects Interface


Effects::GetCapabilities

The GetCapabilities method gets the capabilities of the visualization.

Syntax

HRESULT GetCapabilities(
  DWORD *pdwCapabilities
);

Parameters

pwdCapabilities

[out] DWORD containing the capabilities..

The current values are:

Value | Description
EFFECT_CANGOFULLSCREEN = 0x00000001; | The visualization is capable of full-screen rendering.
EFFECT_HASPROPERTYPAGE = 0x00000002; | The visualization has a property page.
EFFECT_VARIABLEFREQSTEP = 0x00000004; | The visualization will use frequency data with variable size steps. If this bit is set, step size is based on the media sampling frequency divided by BUFFER_SIZE. If this bit is not set and media is played that was sampled at a low frequency, the upper cells will be empty. For example, if an 8KHz sampled file is played and this bit is not set, the upper half of the frequency array (from 8KHz to 22KHz) will be empty. If this bit is set and an 8Khz sampled file is played, the frequency array will range from 20Hz to 8KHz in BUFFER_SIZE steps.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

A default implementation of this method is not included in the visualization wizard.

See Also

  • Effects Interface


Effects::GetCurrentPreset

The GetCurrentPreset method gets the current preset, by number, from the visualization and provides it to Windows Media Player.

Syntax

HRESULT GetCurrentPreset(
  Long  *currentpreset
);

Parameters

currentpreset

[in] Long value specifying the current preset, by number.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

See Also

  • Effects Interface


Effects::GetPresetCount

The GetPresetCount method gets the preset count.

Syntax

HRESULT GetPresetCount(
  Long  *count
);

Parameters

count

[out] Long value specifying the preset count.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

Called by Windows Media Player to obtain the number of presets contained by the visualization.

See Also

  • Effects Interface


Effects::GetPresetTitle

The GetPresetTitle method gets the title of the current preset.

Syntax

HRESULT GetPresetTitle(
  Long  nPreset
  BSTR  *bstrPresetTitle
);

Parameters

nPreset

[in] Long preset number.

bstrPresetTitle

[out] BSTR preset title.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

Called by Windows Media Player to obtain the title of a given preset.

See Also

  • Effects Interface


Effects::GetTitle

The GetTitle method gets the display title of the visualization.

Syntax

HRESULT GetTitle(
  BSTR*  bstrTitle
);

Parameters

bstrTitle

[out] String containing the title.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

This method allows the application to show the user a title when the visualization itself is displayed. The title should be as unique as possible. Do not use titles of visualizations included with the Windows Media Player as this will cause confusion to the user.

See Also

  • Effects Interface


Effects::GoFullscreen

The GoFullscreen method instructs the visualization to switch to full-screen mode.

Syntax

HRESULT GoFullscreen(
  BOOL  fFullscreen
);

Parameters

fFullscreen

[in] Boolean indicating whether to switch to full-screen mode.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

This method is called when the visualization is to go full screen or leave full screen. If the full screen capabilities flag is not returned through GetCapabilities, your visualization will not be asked to go or render full screen. This method will be called before RenderFullScreen is called.

A default implementation of this method is not included in the visualization wizard.

See Also

  • Effects Interface


Effects::MediaInfo

The MediaInfo method sends channel and sample rate data to the visualization.

Syntax

HRESULT MediaInfo(
  LONG  lChannelCount,
  LONG  lSampleRate
  BSTR  bstrTitle
);

Parameters

lChannelCount

[in] Long integer containing the number of channels (one for mono, or two for stereo).

lSampleRate

[in] Long integer containing the sample rate in hertz (Hz). For example, a value of 22500 would specify a rate of 22.5KHz.

bstrTitle

[in] String specifying the title.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

See Also

  • Effects Interface


Effects::Render

The Render method renders the visualization.

Syntax

HRESULT Render(
  TimedLevel*  pLevels,
  HDC  hdc,
  RECT*  prc
);

Parameters

pLevels

[in] Pointer to a TimedLevel structure.

hdc

[in] Specifies a handle to a device context.

prc

[in] Specifies the rectangle the visualization is to be rendered in.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

The device context is normalized by this method.

See Also

  • Effects Interface
  • TimedLevel


Effects::RenderFullScreen

The RenderFullScreen method renders the visualization in full-screen mode.

Syntax

HRESULT RenderFullScreen(
  TimedLevel*  pLevels,
);

Parameters

pLevels

[in] Pointer to a TimedLevel structure.

Return Values

If the method succeeds, your implementation should return S_OK. If it fails, return an HRESULT error code.

Remarks

The GoFullscreen method must be called with a True value before RenderFullScreen can be called.

The user can enter or leave full screen mode by pressing the Alt and Enter keys simultaneously.

A default implementation of this method is not included in the visualization wizard.

If your implementation returns an error from this method, then GoFullscreen(False) will be called to ask your visualization to drop out of full screen mode.

See Also

  • Effects Interface
  • TimedLevel


Effects::SetCurrentPreset

The SetCurrentPreset method gets the current preset from Windows Media Player and sets it in the visualization.

Syntax

HRESULT SetCurrentPreset(
  Long  currentpreset
);

Parameters

currentpreset

[out] Long value specifying the new preset index.

Return Values

If the method succeeds, it returns S_OK. If it fails, it returns an HRESULT error code.

Remarks

This is called by the Windows Media Player to request that the given preset be displayed.

See Also

  • Effects Interface


Visualization Structures and Enumeration Types

Structure or Enumeration | Description
PlayerState | Provides some basic states of Windows Media Player.
TimedLevel | Holds data returned from the spectrum filter.


PlayerState

The PlayerState enumeration type provides some basic states of Windows Media Player.

Number | Description
0 | Stop state
1 | Pause state
2 | Play state

Syntax

typedef enum PlayerState{
  stop_state  = 0,
  pause_state  = 1,
  play_state  = 2
};

Remarks

This enumeration is used by the TimedLevel structure.

See Also

  • Structures and Enumeration Types
  • TimedLevel


TimedLevel

The TimedLevel structure holds data returned from the spectrum filter.

Syntax

typedef struct tagTimedLevel{
  unsigned  char  frequency[2][SA_BUFFER_SIZE];
  unsigned  char  waveform[2][SA_BUFFER_SIZE];
  int  state;
  hyper  timestamp;
} TimedLevel;

Members

frequency

Provides a stereo snapshot of the frequency spectrum of the audio data at a time specified by the Plug-in Manager. It can be used for frequency spectrum effects such as graphic equalizers. The frequency value of the first cell is 20 Hz, and the frequency value of the last cell is 22050 Hz.

waveform

Provides a stereo snapshot of the power value of the audio data at a time specified by the Plug-in Manager as the first element; the next 1024 stereo power values fill out the rest of the array. It can be used for oscilloscope-type effects.

state

Specifies one member of the PlayerState enumeration type.

timeStamp

Specifies the time the snapshot took place, in a 64-bit integer.

Remarks

The array dimension SA_BUFFER_SIZE is currently 1024.

The first dimension of each array corresponds to the channel: 0 is a monaural signal or the left channel of a stereo signal, and 1 is the right channel of a stereo signal. If the signal is monaural, the values in the array that would correspond to the right channel are undefined.

The second dimension contains the sampled levels. The frequency data ranges from 0 to 255. The waveform data represents -128 to 127 but is stored as 0 to 255, so subtract 128 to get the correct value.

This structure is defined in the effects.idl file.

See Also

  • PlayerState
  • Structures and Enumeration Types


Windows Media Metafiles

This reference documents Windows Media™ metafiles. It contains overview and programming guide sections, and a full reference section on metafile element tags, their attributes and values, and special conditions related to each element.

A metafile is a file that contains information about other files. A metafile can be used to list a group of media content files that are to be played in order. Windows Media metafile playlists, simply referred to as playlists in this reference document, are one of the most powerful features of Microsoft® Windows Media™ Technologies. Playlists allow you to control and customize your media content. For instance, with playlists you can schedule content to play in succession or insert advertising or special interest clips into a presentation. A further advantage of playlists is that instead of playing a stream, stopping, starting the next stream, and then waiting for it to finish buffering, Windows Media Services and Windows Media Player work together to play the clips one after the other with minimal buffering time or interruption between them.

Windows Media Technologies and other Internet products provide you with the tools to understand user demographics and dynamically customize a broadcast or message for individual users.

This reference is divided into the following sections.

Section | Description
About Windows Media Metafiles | Introduces Windows Media metafile elements and discusses their purpose.
Windows Media Metafile Guide | Details the steps necessary for creating metafiles. Examples illustrate how to use element tags for specific tasks.
Windows Media Metafile Reference | Explains in detail each of the metafile elements, their attributes and values, and special conditions related to each. Explains metafile file name extensions and their proper use.


About Windows Media Metafiles

Windows Media metafiles are text files that provide information about a file stream and its presentation. Windows Media metafiles, which use the .wax, .wvx, .wmx, and .asx extensions, are based on the Extensible Markup Language (XML) syntax. They are made up of various elements with their associated tags and attributes. Each element in a Windows Media metafile defines a particular setting or action in Microsoft Windows Media Player. Some elements must be located in a specific position in the file relative to other elements. Some elements have required tags and attributes that must be defined in the Windows Media metafile.

The most important part of successfully using Windows Media metafiles is using the correct syntax for the metafile elements. Syntax errors in a Windows Media metafile can cause anything from a single attribute being overlooked, to the metafile not being recognized as valid and failing to work.

Almost as important is the order in which the elements appear in a Windows Media metafile. The attributes of some elements temporarily override the attributes of similar elements in different sections of the metafile. There is a defined Order of Precedence.

Windows Media metafile playlists are Window Media metafiles that provide information that Windows Media Player uses to receive unicast streams, multicast streams, and other supported media from an intranet or the Internet. A metafile playlist is basically a shortcut to media content. A metafile playlist can be sent as e-mail, used as a link reference on a Web page, created dynamically using Active Server Pages (ASP), or exist as a stand-alone file on a local disk drive. A metafile playlist can reference another metafile playlist, an ASP page, or a Windows Media Station (.nsc) file. An .nsc file is used to define a Windows Media Station to Windows Media Player. The basic handling process is the same for each case.


Purpose of a Metafile Playlist

The basic purpose of a metafile playlist is to redirect streaming media content away from browsers to Microsoft Windows Media Player because most browsers will attempt to download the content instead of stream it. A metafile playlist provides information Window Media Player uses to receive streams, such as the Uniform Resource Locator (URL). The metafile playlist can provide the path to media files over the Internet, an intranet or just stored media on a network or local drive. With processing redirected to Windows Media Player, you have greater control over the streaming media.

Metafile playlists are used to control the streaming experience. By combining different media files into a single content stream, you can control and customize their presentation.


Using a Metafile Playlist

Because you cannot link directly from a Web page to a streaming media server, you use metafile playlists. The metafile playlists contain the information needed by Windows Media Player and are stored on a Web server. You can then link from the Web document to a metafile playlist. When a metafile playlist is opened, control transfers to Windows Media Player, which processes the file, connects to the streaming media server, and plays the specified content.

The browser first downloads the metafile playlist to the user's cache directory. Because the metafile playlist is small, this is a very quick step. The user's computer then finds in its file associations table the association of the metafile playlist with Windows Media Player. Windows Media Player opens and interprets the scripting in the metafile playlist, which contains, among other things, the URL of the streaming content. Windows Media Player uses the URL to locate the content and initiate the stream. The metafile playlist scripting then controls the streaming experience.

When a metafile playlist is opened by Windows Media Player version 6.4, the entire file is parsed and all Uniform Resource Locators (URLs) resolved before any content is played. If referenced content includes associated graphics, all referenced graphic files are downloaded before the content is played. This prevents long pauses between pieces of content while a graphic is being downloaded, but can also cause a long delay before the first piece of content plays. For Windows Media Player version 7 or later, each URL is resolved as it is encountered.

Because metafile playlists work through a helper application associated with the ASXMIME type (application/mplayer2 or video/x-ms-asf), they are compatible with any browser that supports helper applications. The examples shown in this document will work with Internet Explorer 4.0 and later, and with Netscape Navigator 4.0 and later on Win32 and MAC platforms. In all examples, you will have to be sure that any media files referenced have valid paths and file names for your environment.

See Also

  • About Windows Media Metafiles
  • Windows Media Metafile Guide
  • Windows Media Metafile Reference


Windows Media Metafile Guide

A Windows Media metafile can be as simple or complex as you need it to be. The most basic Windows Media metafile contains only the Uniform Resource Locator (URL) of some multimedia content on a server. The client, Windows Media Player, parses this information and then opens the media file or stream defined in the Windows Media metafile. A complex metafile can contain multiple files or streams arranged in a playlist, instructions on how to play the files or streams, text and graphic elements such as title, author, and copyright text, personalized ad insertion into a live stream, hyperlinks associated with elements on the Windows Media Player interface, and more.

The following sections provide detailed information on how to create and use Windows Media metafile playlists.

Section | Description
Types of Playlists | Lists available file name extensions.
Creating Metafile Playlists | Describes how to create Windows Media metafile playlists.
Metafile Playlists | Describes metafile playlist usage, scripting, metadata, and processing.
Metafile Extension Guidelines | Describes the preferred use of file name extensions for streaming media files.
Order of Precedence | Describes how metafile playlist elements override other metafile playlist elements.

See Also

  • Windows Media Metafile Elements Reference


Types of Playlists

Windows Media metafile playlists, simply referred to as playlists in this document, have .wax, .wvx, or .asx extensions. Playlists with these extensions are used to access files with .wma (Windows Media Audio), .wmv (Windows Media Video), and .asf (Windows Media file) extensions respectively.

See Also

  • Metafile Extension Guidelines.
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Creating Metafile Playlists

You can create a playlist using any text editor, such as Microsoft Notepad. Open your text editor. Type the script entries you want to implement. After you have finished typing into Notepad, save the file with an appropriate file name and file name extension. For more information about extensions, see Metafile Extension Guidelines. Typically the file name is the name of the Windows Media file or stream followed by an extension of .wax, .wvx, or .asx. For example, if your media content is a Windows Media audio file that has a .wma extension, use the .wax extension when naming the playlist. Playlists must not include any formatting codes from a word processor, such as Microsoft Word. To be sure no formatting codes are included in the playlist, save the file as a plain text or ASCII file.

Note Elements and attributes are not case sensitive. The text used in the playlist to define an element or attribute can be either uppercase or lowercase, or a mixture of both.

If an element does not have any child elements (those that modify or are contained within another element), a single slash character (/) can be used at the end of the opening tag, just before the '>', in place of a closing tag. Child elements of an element must appear between the opening and closing tag for that element, otherwise they are not child elements for that element, and are ignored or cause an error in the syntax of the playlist.

The first four characters of a playlist must be "<ASX". The ASX element is used in all playlists whether their extension is .wax, .wvx, or .asx, There must be only one ASX element per playlist. This element identifies the file as a Windows Media metafile playlist. It does not specify the type of playlist.

The ASX element has three possible attributes:

VERSION

The VERSION attribute is required and must follow immediately after the ASX element, for example "<ASX version = "3.0">". The current version number is 3.0. Windows Media Player supports all previous versions. Acceptable values for the VERSION attribute include both 3.0 and 3 (with no decimal point).

PREVIEWMODE

The PREVIEWMODE attribute is optional. It provides another mechanism for specifying how long to render a clip. If the value of the PREVIEWMODE attribute is YES, Window Media Player will render each clip for the duration specified by the element PREVIEWDURATION. Each clip can have a PREVIEWDURATION specified.

BANNERBAR

The optional BANNERBAR attribute defines whether the Windows Media Player control reserves space for a banner graphic. (Use the BANNER element to specify the graphic to display.) If the value of BANNERBAR is FIXED, Windows Media Player reserves banner space for the show and for every clip, whether or not the metafile playlist specifies a banner for the show or clip. This will keep the size of the Windows Media Player window the same (except when the video size changes) regardless of the absence or presence of a banner graphic. If the show or clip does not have a banner associated with it, the space reserved for one is black. If the value of the BANNERBAR attribute is AUTO, Windows Media Player reserves space for the banner only when the show or clip includes one.

<ASX version="3.0" BANNERBAR="AUTO" >

For more information about the three attributes of the ASX element, see the reference entry for the ASX Element.

An ASX element contains ENTRY child elements that define information about the media files to be accessed. Each ENTRY element must contain a REF element that specifies the path to the media file to be streamed. There must be at least one ENTRY or ENTRYREF element within an ASX element.

Other elements defined within the scope of the ASX element, such as TITLE and AUTHOR, are associated with the metadata displayed by Windows Media Player.

The simplest playlists are created by adding multiple ENTRY elements with a single REF element to a metafile. Each ENTRY element in a metafile playlist is rendered in the order it appears in the file as though the user had manually opened each clip.

Example Code

<!--A simple playlist with entries to be played in sequence.-->
<ASX version = "3.0">
    <Title>The Show Title</Title>
    <Entry>
        <Ref href = "mms://MYserver/Path/title1.wma" />
    </Entry>
    <Entry>
        <Ref href = "mms://MYserver/Path/title2.wma" />
    </Entry>
    <Entry>
        <Ref href = "mms://MYserver/Path/title3.wma" />
    </Entry>
</ASX>

Be sure that the playlist is working by double-clicking it in Windows Explorer. Windows Media Player should open and start streaming the media content. After you have confirmed that the playlist works, save it to your Web server along with your Web pages, and link to it by means of an HREF element, or embed it in a Web page using the Windows Media Player OBJECT element.

See Also

  • BANNER Element
  • Example Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Nesting Metafiles

A metafile can reference another metafile. To reference another metafile, use the ENTRYREF element. An ENTRYREF element in the primary metafile points to an external metafile.

The Windows Media Player control processes the ENTRY elements of the referenced metafile as if they were included in the primary metafile at the position of the ENTRYREF element. However, it skips any ENTRY elements in the referenced metafile that have the SKIPIFREF attribute set to YES.

The Windows Media Player control ignores any ENTRYREF elements in the referenced metafile. Thus, metafiles can only be nested one level deep. Windows Media Player also ignores the ASX element and its attributes in the referenced file.


Using ASP Pages to Dynamically Create Windows Media Metafile Playlists

You can use Active Server Pages (ASP, or .asp files) to dynamically generate playlists based on information provided by users. An ASP page is a dynamic Web page used in conjunction with Microsoft® Internet Information Service (IIS). ASP is an environment in which you can combine HTML, scripts, and reusable ActiveX server components to create dynamic and powerful Web-based business solutions. ASP pages enable server-side scripting for IIS with native support for both Microsoft Visual Basic® Scripting Edition (VBScript) and Microsoft Jscript®. This discussion assumes that you are familiar with ASP and defining variables.

All header information must be contained on the first line of the ASP page string returned to Windows Media Player.

When you use ASP pages to generate playlists, you must define a Response type variable, as well as a Response expire variable in the ASP page because of latency issues with Windows Media Player. The response type must be a valid extension for Windows Media metafiles. Valid types include wma, wax, wmv, wvx, asf, and asx.

The following code is an example of an ASP page used to generate a Windows Media metafile playlist.

<%Response.ContentType = "video/x-ms-wma"%><%Response.expires=0 %>
<ASX VERSION="3.0">
    <TITLE>Your title here</TITLE>
    <ENTRY>
        <REF HREF ="mms://YourPath.com/pubpt/filename.wma" />
    </ENTRY>
</ASX>


Metafile Playlists

Windows Media metafile playlists are used to organize stream content and presentation. A playlist can simply redirect Windows Media Player to the content to be streamed, but more commonly will provide a list of files to be played sequentially. A more complex playlist may contain repeats, commercial inserts, and information about the items in the list.

Another advantage of playlists is that instead of playing a stream, stopping, starting the next stream, and then waiting for it to finish buffering, Windows Media Services and Windows Media Player work together to play the clips one after the other with minimal buffering time or interruption.


Control of Playlists

Control of playlists is maintained by the client. Playlists are parsed by Windows Media Player, which takes actions based upon the elements of the playlist. The client has control of the streaming experience.


Custom Graphics in Windows Media Player

With Windows Media metafile scripting, you can add graphics elements to Windows Media Player as the stream plays. There are two basic types of graphics you can add.

Type | Description
BANNER | Using the BANNER element you can place a banner (32 pixels high by 194 pixels wide ) image on Windows Media Player at the bottom of the video display area. You can then use a child element to add a hyperlink to the banner.
LOGO By setting the STYLE attribute of the LOGO element to ICON, you can place a small (16 pixels x 16 pixels) image next to the Title of the Show, or next to the Show status on Windows Media Player. This graphic replaces the icon next to the Show title when within the ASX element scope, and it replaces the graphic next to the Clip title when within an element scope.

By setting the STYLE attribute of the LOGO element to MARK, you can display a graphic that is 82 pixels wide and 30 pixels high. The parent element of the LOGO element must be ASX. The MARK STYLE graphic is displayed in the lower right corner of the video display area (allowing for a six-pixel border). This graphic is displayed before and after the clip plays.

The LOGO element is supported by Windows Media Player version 6.4. The LOGO element is not supported by later versions of Windows Media Player.

Example Code

<LOGO href = "http://Myserver/MyPath/msdtx.ico" STYLE = "ICON" />
<LOGO href = "http://Myserver/MyPath/msdtx.ico" STYLE = "MARK" />

See Also

  • Metafile Playlists
  • Modifying the Display
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Logging Stream Data

Logged information can be acquired and used to determine viewer behavior, for example, how often a stream is viewed, or if a specific user viewed a stream and for how long at what quality.

The LOGURL element enables a client metafile playlist to post log statistics to the origin server and any other valid Web location specified. This element instructs Windows Media Player to submit log data to all of the specified URLs in scope, in addition to the origin server.

The Windows Media Format SDK supports the LOGURL element through the IWMSReaderNetworkConfig interface and the following methods:

HRESULT AddLoggingUrl(LPCWSTR pwszUrl);
HRESULT GetLoggingUrl(DWORD dwIndex, LPCWSTR pwszUrl, DWORD *pcchUrl);
HRESULT GetLoggingUrlCount(DWORD *pdwUrlCount);
HRESULT ResetLoggingUrlList();

Example Code

<ASX version="3.0">
  <LOGURL href="http://foo.com/log.asp?SoemArg=SomeVal" />
  <ENTRY>
    <REF href="mms://ucast.foo1.com/Media1.wma" />
    <LOGURL href="http://foobar.com/cgi-bin/logging.pl?SomeArg=SomeVal" />
    <LOGURL href="http://bar.com/WMLogging.dll?SomeArg=SomeVal" />
    <REF href=rtsp://ucast.blah.com/Media1.wma" />
  </ENTRY>
  <ENTRY>
    <REF href="mms://ucast.blah1.com/Media2.wma" />
  </ENTRY>
</ASX>

See Also

  • Metafile Playlists
  • Windows Media Metafile Elements Reference


Retrieving Metadata

This topic applies to Windows Media Player 7 or later only.

While a show or clip is playing, your script can retrieve metadata, such as title and author, by using the getItemInfo methods of the Windows Media Player Media and Playlist objects. You can retrieve metadata from the ASX scope using Playlist object methods and from the ENTRY scope using Media object methods.

For example, to retrieve the values for AUTHOR, ABSTRACT and PARAM in the file below, use the getItemInfo method of the Playlist object. The attribute name is required for this method. Attribute names can be obtained by providing the index number to the attributeName property. The available indexes for a Playlist object can be obtained using the attributeCount property.

Example Code

<ASX version="3.0">
    <AUTHOR>My Talking File</AUTHOR>
    <ABSTRACT>Talking File Album</ABSTRACT>
    <PARAM name="one" value="111"/>
    <ENTRY>
        <REF href="Artists_Only.wma"/>
        <TITLE>Artists Only</TITLE>
        <COPYRIGHT>2000</COPYRIGHT>
        <PARAM name="three" value="333"/>
    </ENTRY>
    <PARAM name="two" value="222"/>
</ASX>

To retrieve the values of the current Media object in the ENTRY scope for REF, TITLE, COPYRIGHT, and PARAM ("three"), use the currentMedia property of the Player object. Use the attributeCount property of the Media object to determine the number of attributes available for the specified Media object. Use index numbers with the getItemInfoByAtom method to retrieve attribute values. Use index numbers with the getAttributeName method of the Media object to determine the names of the available attributes, and then use the results with the getItemInfo method.

For an example of using Windows Media Player object methods to retrieve metadata, see Playlist.attributeCount.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Guide


Using Metafile Playlists

Playlists specify how the streaming media or media files will be played and what metadata Windows Media Player will display.

This section explains several ways you can use playlists. The section is divided into the following topics.

Topic | Description
Modifying the Display | Adding text, links, and images.
Redirection | Using playlists to redirect the browser to Windows Media Player and specifying the URL of a stream or media file to play.
Accessing Media | Using metafile elements and their child elements to specify the content to access, and the order and duration of their playback.
Using Live Event Stream Switching | Using the EVENT element to specify a media stream to access and then resume playing the original stream. Used for ad insertion.
Using Metafiles for Seamless Stream Switching | Using the EVENT element to preload the next media stream to access to avoid gaps in the presentation.
Using Announcements | Using a metafile to provide information about the URL for a media stream, including the multicast IP address, port, stream format, and other station settings.
Using URL and Server Rollover | Using metafile playlists to provide a means of automatically rolling over to alternate content sources when a stream cannot be accessed or played.
Using Custom Parameters and Commands | Using the PARAM element to define custom elements to provide additional metadata.
Personalizing Media Delivery | Using user preferences to determine broadcast content.

See Also

  • Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Modifying the Display

Playlists can alter the Windows Media Player user interface in four main ways:

Text properties

Windows Media Player enables the display of Title, Author, Copyright, and Description metadata text. Clip metadata can come from the stream or media file, or it can come from a playlist. Show metadata comes from the playlist. In general, playlists are a better method of passing text properties to Windows Media Player, especially if text elements are likely to change. It is easier to edit text in a playlist than to re-author a media file. And because properties read from a playlist override those contained in the media file, you can easily update display text by adding the new text to the corresponding property in a playlist. In the following example, the text of the Title and Author metadata in the playlist overrides the Title and Author text contained in the media file, sample.wma.

DESCRIPTION text is retrieved from a Windows Media file referenced in an ENTRY element unless there is an ABSTRACT element in a metafile playlist. If there is ABSTRACT text, it will be displayed, overriding the DESCRIPTION text.

<ASX version="3.0" BANNERBAR="AUTO" >
    <ENTRY>
        <BANNER HREF="YourPath\2.gif">
        </BANNER>
        <TITLE>Upgrade</TITLE>
        <AUTHOR>Ad Department</AUTHOR>
         <REF href="YourPath\sample.wma"/>
    </ENTRY>
</ASX>

Image properties

Banner images can be added to the user interface of Windows Media Player. The graphic can be used for advertising, providing information, and providing access to Web sites, to name a few possibilities.

Use the BANNER element to specify a graphic image (32 pixels high by 194 pixels wide) for display by Windows Media Player. The graphic is displayed below any video content. A hyperlink can be added to the banner using the MOREINFO child element.

A ToolTip can be defined by an ABSTRACT element within the scope of the BANNER element. Any defined ToolTip text can be displayed by pausing the mouse pointer over the banner graphic. Selecting the banner graphic with the mouse pointer will activate any hyperlink defined with the MOREINFO element.

The preferred BANNER graphics format is the GIF format. The JPG format can be used if the graphic is properly sized. The ICO format can be displayed by Windows Media Player 6.4.

The previous example illustrates use of the BANNER element.

Note BANNER images are not supported with DRM files or when Windows Media Player is embedded in a Web page.

For more information about banners, see Custom Graphics in Windows Media Player .

MOREINFO properties

Text and image areas of the user interface can be associated with URLs. During playback, users can select one of these sections to connect to the URL associated with it in their Web browser. For example, you can associate an advertiser’s Web site with an ad banner image as shown in the following code snippet.

<BANNER HREF="YourPath\2.gif">
    <ABSTRACT>More Information.</ABSTRACT>
    <MOREINFO HREF="http://YourSite.com" />
</BANNER>

ABSTRACT text

ABSTRACT text is used to display a short pop-up description of the text or image areas of the user interface it is associated with. During playback, if the mouse pointer hovers over one of these areas, a ToolTip appears beside the mouse pointer displaying the ABSTRACT text associated with the area. ABSTRACT text is retrieved from a metafile and is defined with the ABSTRACT element. The ABSTRACT element can be a child element of either an ENTRY or a BANNER element.

See Also

  • Metafile Playlists
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Redirection

The playlist will redirect the browser to Windows Media Player to play the designated media stream or media file. The most basic metafile playlist contains only the Uniform Resource Locator (URL) of a media file.

To create a basic metafile playlist , open your favorite text editor, such as Microsoft Notepad, and type the following example code.

<ASX version="3.0">
   <ENTRY>
      <REF HREF="PathToYourFile"/>
   </ENTRY>
</ASX>

Substitute a valid path to your Windows Media file using the syntax in the following table.

Source of content | Syntax
Content is a file on a Windows Media server | mms://ServerName/Path/FileName.wma
Content is a broadcast multicast that is accessed from a Windows Media station | http://WebServerName/Stations/kxyz.nsc
Content is a broadcast unicast that is accessed from a publishing point on a Windows Media server | mms://ServerName/PublishingPointAlias
Content is a file on a Web server | http://WebServerName/Path/Filename.wma
Content is a file on a local hard disk drive | file://c:\Path\Filename.wma
Content is a file on a network share | file://\\ServerName\Path\Filename.wma
Content is a file on a Windows Media server | mms://ServerName/Path/FileName.wmv

Save the file you have created with a file name and extension as described in File Name Extensions. Double-click it in Windows Explorer. Windows Media Player should open and start streaming the content. You can save the file to your Web server, along with your Web pages, and link to it with an HREF element, or embed it in a Web page using the Windows Media Player OBJECT tag.

See Also

  • Metafile Playlists
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Accessing Media

Use playlists to specify and to control the streaming media or media files that Windows Media Player plays.

Use the ENTRY element to specify a single media element (a media file or a live stream) and any child elements (such as images, MOREINFO links, and ABSTRACT text). Use an ENTRYREF element to specify a playlist. A playlist can contain one or more ENTRY or ENTRYREF elements. Windows Media Player executes a playlist by starting with the first entry and then playing each entry in turn until the list is finished.

An ENTRY element can point to any type of media that Windows Media Player can play. This includes not only .wma, .wmv, .asf, and .avi files, to name a few, but live streams as well. By using a series of ENTRY or ENTRYREF elements to reference media content, you can use a playlist to send a single stream that consists of multiple sources. The referenced streams will play sequentially and be seen as one continuous stream by the viewer. For example, the playlist can contain two ENTRY elements, a standard introduction from a Windows Media file with a .wma extension, and a live Windows Media stream.

Note A playlist must not contain links to media files that have content created with different versions of Digital Rights Management (DRM). In a metafile playlist, if there are links for media files with DRM version 1 content and for media files created with later DRM versions, Windows Media Player will only play the DRM version 1 content.

Controlling Playback

Use playlists to control not only which media clip is played, but also which portions of the clip are played and how. You can use playlists to define a set of clips to be looped or repeated, to set the duration of play, and to assign start times, and start and end markers for each entry. The STARTTIME, STARTMARKER, and ENDMARKER elements work in conjunction with markers in the media file.

For example, the following playlist uses an ad banner and the associated MOREINFO link in one ENTRY, and references a STARTMARKER and ENDMARKER.

·<ASX version ="3.0">
·<Title>Windows Media Example</Title>
·<Abstract>Windows Media Technologies</Abstract>
·<MoreInfo href = "http://Yourpath.com"/>
·    <!--This is the first Entry -->
·    <Entry>
·        <Title>This is the ad</Title>
·        <Author>Ad Department</Author>
·        <Copyright>2000</Copyright>
·        <Abstract>This is a description of the ad.</Abstract>
·        <MoreInfo href = "http://SomePath.com/"/>
·        <Ref href="ad.wma"/>
·        <Banner href ="purchase.gif">
·           <Abstract>Click here to go to our Web site.</Abstract>
·           <MoreInfo href = "http://AnotherPath.com/" />
·        </Banner>
·     </Entry>
·    <!-- This is the second Entry -->
·    <!-- The Windows Media file plays from Segment2 to Segment3 -->
·    <Entry>
·        <Title>Playlist Clip Number Two</Title>
·        <Author>Windows Media</Author>
·        <Copyright>2000</Copyright>
·        <Ref href="show.wma"/>
·        <StartMarker Name = "Segment2" />
·        <EndMarker Name = "Segment3" />
·    </Entry>
</ASX>

Setting Duration

Use the DURATION element to specify how long to play a clip or set of clips. You can also use the PREVIEWMODE attribute of the ASX element in conjunction with the PREVIEWDURATION element to specify how long to play a clip or set of clips. Set the PREVIEWMODE attribute to YES to use the PREVIEWDURATION element to specify how long to play the associated clip. In Windows Media Player 7 or later, the PREVIEWDURATION and DURATION elements have the same behavior. In Windows Media Player 6.4, the PREVIEWDURATION can be ended, or begun, with the Windows Media Player preview button. When the PREVIEWDURATION is ended the associated clip or clips will then play in their entirety.

See Also

  • Metafile Playlists
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Using Live Event Stream Switching

Streaming media can also be controlled by the interaction of script commands embedded in a media stream with Windows Media metafile elements in a metafile playlist.

An event is a particular type of script command embedded in a media stream or media file. When the Windows Media Player control receives the script command, it processes the event as defined by the EVENT element in the metafile playlist. Windows Media Player switches from the current stream it is rendering and renders the content referenced in the metafile playlist EVENT element. The EVENT element is usually used in live production.

An EVENT element looks similar to an ENTRY element, but each handles the playback of streams and media files differently. The ENTRY element is used to create playlists. A stream or media file referenced in an ENTRY element starts playing as soon as the stream or media file referenced in the previous ENTRY finishes. A stream referenced in an EVENT plays only when a specific script command is received. For example, when Windows Media Player receives a script command with type string "EVENT" and the command string "Adlink", it searches the playlist for the following elements.

<EVENT NAME="Adlink" WHENDONE="RESUME">
    <ENTRY HREF=mms://YourPath.com/adlink.wma />
</EVENT>

Windows Media Player then switches from the live stream to play the stream or media file contained in the EVENT, in this case Adlink.wma. The code WHENDONE="RESUME" instructs Windows Media Player to resume playing the previous stream as soon as Adlink.wma is finished.

Note Failure to handle every event embedded in a media stream or media file may yield unexpected results.

If you want to use live event stream switching, you must include one EVENT element in your playlist to handle each event script command embedded in the media streams or media files in your playlist. Before you create your playlist, you must know the details about which script commands are embedded in your digital media content. If there is an event script command that you want Windows Media Player to ignore, include an EVENT element in your playlist to handle the event, but reference a dummy URL in the event handler.

Ad Insertion

This technique can be used for ad insertion. For example, during a live Internet broadcast of a ball game, a command can be sent at the beginning of every commercial break that instructs each client (Windows Media Player) to play commercials listed in its playlist. When clients finish playing the commercials, the playlist instructs each client to cut back to the live broadcast. The EVENT media content will be rendered only when the streaming media being accessed broadcasts embedded scripting with the matching EVENT name.

The possibilities inherent in EVENT switching are best appreciated by contrasting how ads reach viewers through standard, over-the-air broadcasting with how ads can reach viewers using Windows Media Technologies. Historically, broadcast ads could only be roughly targeted at viewers, using ratings data as the primary criteria. Ads sent using Windows Media Technologies can be aimed directly at the target user because EVENTs and playlists can be built on the fly based on user input. For more information, see Personalizing Media Delivery.

You can also use metafile playlists to display customized graphics, audio and text for advertising. You can use the BANNER element as a child element of an EVENT to display an advertising message graphic. The BANNER element provides the path and file containing the graphics for your advertising banner. You can also provide a link to a site or file using the MOREINFO child element. The URL in the MOREINFO element can provide a link to even more advertisements on the Web.

Example Code

<BANNER HREF="SomePath\2.gif">
    <ABSTRACT>Read This Ad and Buy.</ABSTRACT>
    <MOREINFO HREF="http://MyURL.com" />
</BANNER>

The following example inserts the ad Advert.wma into the broadcast unicast stream BallGame when a client receives a script command EVENT with the NAME attribute set to "Time-Out". CLIENTSKIP is set to NO to prevent the streamed ad from being skipped. In this example, the streamed ad must be played before returning to the original stream. When the ad is finished, the client resumes playing the original stream.

Example Code

<ASX VERSION="3.0">
    <ENTRY>
        <REF HREF="mms://MyPath/BallGame" />
    </ENTRY>
    <EVENT NAME="Time-Out" WHENDONE="RESUME">
        <ENTRY>
            <REF HREF = "mms://MyServer/Advert.wma"
                CLIENTSKIP = "NO" />
       </ENTRY>
    </EVENT>
</ASX>

See Also

  • Metafile Playlists
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Using Metafiles for Seamless Stream Switching

You can facilitate seamless stream switching using metafile playlists. Usually, when a piece of content ends, buffering occurs for the next clip or stream before it opens (if it is content received from a streaming media server). Microsoft Windows Media Services enables you to eliminate, or at least minimize, this buffering time and have another piece of streamed content begin playing nearly immediately. The normal mode of operation for Windows Media Player is to open the next media stream referenced by the playlist 20 seconds before the end of the currently rendered stream. This generally provides a seamless transition between media streams, depending on other factors such as Web access times.

Use the EVENT element in a playlist in conjunction with OPENEVENT commands from the encoder to facilitate seamless switching between streams or files. Sending an OPENEVENT command 20 seconds or more prior to the EVENT command can minimize delays in stream switching. Then Windows Media Player is able to preload a portion of the upcoming streaming content into a buffer.

Use Windows Media Encoder to send a script command in the stream using the following format:

OPENEVENT eventname

The event name must be the one defined in the EVENT element in the playlist. When Windows Media Player receives an OPENEVENT script command from the encoder, it looks to the EVENT element in the playlist and begins buffering the clip or stream defined in the EVENT element. Windows Media Player then holds this information until the actual event of the same name. When the named event is received, Windows Media Player switches to that previously buffered content.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Player.scriptCommand
  • Using Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Using Announcements

An announcement is a file that contains information about the URL for a media stream, including the multicast IP address, port, stream format, and other station settings. Announcements are created by Windows Media Administrator when a unicast or multicast publishing stream is created. The client can quickly load the announcement file, then proceed to access the streaming media file.

For a unicast publishing point, the publishing point media stream is opened. For a multicast publishing point, the URL is extracted from a broadcast station file with an .nsc extension, and the streaming media is accessed. Unlike a unicast stream, no header information is contained in a multicast stream. That information comes from the broadcast station file with an .nsc extension. Windows Media Player usually first opens an announcement file, which is one use for metafile playlists, that points to the location of the broadcast station file.

Example Code

<ASX VERSION="3.0">
    <TITLE>title</TITLE>
    <ENTRY>
        <REF HREF="mms://server_name/pubpoint"/>
    </ENTRY>
</ASX/

See Also

  • Creating Metafile Playlists


Using URL and Server Rollover

You can use metafile playlists to provide a means of automatically rolling over to alternate content sources when a stream cannot be accessed or played. You can use this rollover method to specify sources of the same content on different servers or different types of servers. You can, for example, specify a first alternate on a different Windows Media server. If that content fails to play, the client can roll over to a second alternate on a Web server. Windows Media Player automatically tries to roll over to different protocols according to its Windows Media property settings before trying the rollover URLs in the playlist.

Set server and protocol rollover by placing multiple REF elements in succession within one ENTRY element. Each REF element specifies an alternate location or protocol for a media file or stream.

Example Code

<!--Server and protocol rollover is set for the file Rollover.wma.-->
<ASX version="3.0">
    <TITLE>MyServer Rollover</TITLE>
   <ENTRY>
      <REF HREF="mms://MyServer1/Path/Rollover.wma"/>
      <REF HREF="mms://MyServer2/Path/Rollover.wma"/>
      <REF HREF="mms://MyServer3/Path/Rollover.wma"/>
      <REF HREF="http://MyWebServer/Path/Rollover.wma"/>
   </ENTRY>
</ASX>

See Also

  • Creating Metafile Playlists


Using Custom Parameters and Commands

You can create custom parameters to pass additional metadata in a metafile playlist by using the PARAM element. Use the NAME attribute of the PARAM element to define the custom parameter name. Use the VALUE attribute to define the value for the named custom parameter.

Retrieve PARAM metadata by using the getItemInfo methods of the Media and Playlist objects, for Windows Media Player 7 or later. For an example using these methods to retrieve metadata, see the attributeCount method of the Playlist object.

Use the GetMediaParameter method for retrieving PARAM metadata with Windows Media Player version 6.4.

The following example metafile playlist shows the use of the PARAM element to define custom parameters.

<ASX version="3.0" BANNERBAR="auto" >
    <TITLE>Example Media Player Show</TITLE>
    <PARAM NAME="Director" VALUE="Jane D." />

    <ENTRY>
        <TITLE>Example Clip</TITLE>
        <REF HREF="http://SomeSamples.com/media.wma" />
        <PARAM NAME="Title" VALUE="Example Clip" />
        <PARAM NAME="Location" VALUE="North America" />
        <PARAM NAME="Release Date" VALUE="March 1998" />
    </ENTRY>

    <ENTRY>
        <TITLE>Another Clip</TITLE>
        <REF HREF="http://SomeSamples.com/more_media.wma" />
        <PARAM NAME="Title" VALUE="Another Clip" />
        <PARAM NAME="Location" VALUE="Japan" />
        <PARAM NAME="Release Date" VALUE="December 2000" />
    </ENTRY>
</ASX>


Personalizing Media Delivery

Unlike one-way communication that broadcasts identical content to a mass audience, Windows Media Technologies provides you with the tools to use demographics to individualize broadcasts. With the Internet, two-way communication on a large scale is readily available. This dynamic interchange of information enables content providers to know their audience and respond with customized presentations.

The following example, using a fictional company, illustrates how delivery of streaming content can be personalized. This discussion assumes that you are familiar with Active Server Pages (ASP, or .asp files) and defining variables.

News Network is a fictional broadcast news organization that has expanded its operations to include a Web site. The main feature of the site is a section where users can create their own personalized newscasts. Instead of viewing a traditional newscast that is aimed at a mass audience, a user views a complete news program that contains only topics of personal interest. The following sequence describes a typical user experience.

  1. A new user goes to the site, and clicks Create Your Personal Newscast.
  2. A preference form opens. On this form, the user answers questions regarding personal preferences, such as favorite news stories, least favorite news stories, hobbies, and usual method of receiving daily news.
  3. The user sends this information, and a few seconds later views a complete, 15-minute, personal newscast containing program content, transitions, and commercials. Selection of each media element, including commercials, is based on the user profile, and is accomplished automatically with Windows Media Technologies components and off-the-shelf Internet tools.

The following list describes how the various tools interact to create a personalized newscast.

  1. The preference form that the user fills out is an Active Server Page (ASP) (Choices.asp). Data obtained from the preference form is analyzed by two server components. One component uses the information to query a Microsoft® SQL Server™ database of news stories. The other component is an ad server that uses a complex set of rules based on contractual requirements and demographics to schedule ads appropriate to the user at that time.
  2. The two databases return different portions of a playlist. The news story database returns a set of appropriate story Entries, and the ad server returns a set of appropriate commercial Entries.
  3. A second ASP page (PlayShow.asp) receives the Entries from the news story database and ad server, and combines those with standard show open, close, and transition Entries. All Entries are then laid out according to the template provided by PlayShow.asp, and the ASP page returns a playlist to the user.
  4. The embedded Windows Media Player control on the user’s computer plays the playlist from beginning to end, and the user views a personalized newscast.

The following example is a portion of a playlist file that a user might receive. Ad banners, MOREINFO links, and ABSTRACTS have been added to it.

<ASX Version="3">
<TITLE>MyPersonalized NewsCast</TITLE>
<ENTRY ClientSkip="no">
    <!—- Commercial Element 1 -->
    <REF HREF="mms://SomeURL/Commercial.wma" />
    <BANNER HREF="http://SomeURL/images/MoreInfo.gif" >
        <MOREINFO HREF="http://SomeURL" target="_blank" />
    <ABSTRACT>Courtesy of Windows Media Technologies
    </ABSTRACT>
    </BANNER>
</ENTRY>
<ENTRY>
    <!—- Program Element 1 -->
    <TITLE>A Celebrity's Life</TITLE>
    <COPYRIGHT>Copyright 2000</COPYRIGHT>
    <REF HREF="mms://SomeURL/SomePath/TheFile.wma" />
    <ABSTRACT>
     :: A celebrity continues to captivate the world, even after death.
    </ABSTRACT>
    <COPYRIGHT>Copyright 2000-- All Rights
         Reserved
    </COPYRIGHT>
</ENTRY>

<ENTRY>
    <!—Program Element 2 -->
    <TITLE>Fire:: Wildfires appear to be just the beginning</TITLE>
    <COPYRIGHT>Copyright 2000</COPYRIGHT>
    <REF HREF="mms://SomeURL/SomePath/MyFile.wma" />
    <ABSTRACT>
        :: So far, more than 100,000 acres have burned.
    </ABSTRACT>
    <COPYRIGHT>Copyright 2000 -- All Rights Reserved
    </COPYRIGHT>
</ENTRY>
</ASX>

The example companies, organizations, products, people and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred.

See Also

  • Creating Metafile Playlist
  • Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Using Relative Links in Metafiles

Relative links are a fully supported feature of Windows Media metafiles. You can use relative links in metafiles much like you use them in HTML documents. The use of relative links enables you to create metafiles that are portable, meaning you can copy or move an entire directory structure to another server without updating the paths to graphic files used as logos or banners or the HREF attributes of MOREINFO elements (if they reference files on the same Web server as the stored metafile). Relative links work, in any application that supports them, because the parts of the URL not included in the HREF attribute of an element are included in the URL sent by the application to the server when that URL is requested. This means that the protocol (such as http://), the server name, and the virtual directory in which the file containing the relative link is located are all included in the URL that is sent to the server. If the media file, or URL you link to using a relative link does not reside on the same server as the metafile, the relative link is not valid.

Note This information on relative links is correct only when using a link to metafiles that are opened in the stand-alone Windows Media Player. When you use the embedded Windows Media Player control, all links are relative to the page on which the control is hosted, unless the BASE child element of the ASX element is used to redirect the relative path.

All relative links in the metafile must be fully relative, not drive-relative, for streaming media. When a URL begins with a "\" character, the link is drive-relative. Windows Media Player attempts to open the file linked to on the drive where the metafile was opened from, usually a Web server. Because Web servers use virtual directories, Windows Media Player tries to find the specified stream or media file in a subdirectory of a virtual directory on the Web server where the metafile was opened from. A user would not have access to a server directory. The example in this section illustrates the use of a fully relative link.

You can use drive-relative links when using metafiles on a single computer where all media files linked to in the metafile playlist exist on a storage device in that computer. However, you cannot stream media in this manner.

When you use a link to another metafile to allow for relative links, the name displayed as the Title by Windows Media Player is the Title in the original metafile.

Relative links cannot be used for URLs to a streaming media server because different protocols are used for accessing streaming media content.

In the following example playlist, the first ENTRYREF contains a URL for another playlist, relative.wax.

<ASX>
    <ENTRYREF HREF=http://example.microsoft.com/metafiles/relative.wax"/>
</ASX>

The following example is the file relative.wax
This file contains relative links.
<ASX version = "3.0">
    <BANNER HREF = "graphics/logo1.jpg">
        <MOREINFO HREF = "category1/category1.htm" />
    </BANNER>
    <ENTRY>
        <REF HREF = "mms://samples.microsoft.com/myfile.wma" />
    </ENTRY>
</ASX>

The URL containing the reference to the playlist, relative.wax, can exist in a metafile playlist anywhere that is accessible to the user. For the URL to be processed successfully, there must be a Web server named "examples.microsoft.com". That Web server must have a virtual directory defined as "metafiles". The referenced playlist, relative.wax, must exist on the Web server named "examples.microsoft.com" in the virtual directory "metafiles".

For the referenced media files in the playlist relative.wax to be successfully accessed and played, there must be a directory named "Graphics" which is a subdirectory of the server's virtual directory "metafiles". The graphics file Logo1.jpg, referenced in the BANNER element, must be the subdirectory named Graphics.

Similarly a document named Category1.htm must reside in a subdirectory named Category1. The directory named Category1 must exist as a subdirectory of the virtual directory "metafiles" on the Web server examples.microsoft.com.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Elements Reference.
  • Windows Media Metafile Guide


Example Playlists

Following are three example playlists. To use these examples you must ensure that you have substituted valid paths and file names that are accessible to Windows Media Player.

Example playlist | Description
A Basic Playlist | A simple playlist.
An Advanced Playlist | A playlist with a more complete set of playlist elements.
An Example Radio Station Playlist | A playlist that scans three radio stations.


A Basic Playlist

The following playlist example shows a basic set of playlist elements. When writing your own code, you will need to change all URLs and file names to valid file names that are accessible to your Windows Media Player.

Code Example

<ASX version = "3.0">
<TITLE>Basic Playlist Demo</TITLE>
    <ENTRY>
        <TITLE>An Entry in a basic playlist</TITLE>
        <AUTHOR>Microsoft Corporation</AUTHOR>
        <COPYRIGHT>(c)2000 Microsoft Corporation</COPYRIGHT>
        <REF HREF = "mms://YourServer/path/Yourfile.wma" />
    </ENTRY>
</ASX>

The following table provides details on the use of each element in the example code.

Line | Description
<ASX version = "3.0"> | Identifier for the client (Windows Media Player) that this is a Windows Media metafile playlist. The VERSION attribute, specifies the version number of the metafile elements.
<TITLE>Basic Playlist Demo</TITLE> | The TITLE element identifies the title of the playlist as a whole. Windows Media Player displays this metadata as the show title.
<ENTRY> | Begins the ENTRY element. An ENTRY element is a way to define a particular clip in a playlist
TITLE>An Entry in a the basic playlist</TITLE> | Identifies the title of the playlist clip . It is different than the previous TITLE element because this one is nested within an ENTRY element. Windows Media Player displays this metadata as the clip title.
<AUTHOR>Microsoft Corporation</AUTHOR> | The AUTHOR element identifies the author of the media clip . Windows Media Player displays this metadata as the clip AUTHOR.
COPYRIGHT>(c)1999 Microsoft Corporation</COPYRIGHT> | The COPYRIGHT element identifies any copyright associated with the media content. This information is displayed as the clip COPYRIGHT by Windows Media Player.
<!-- This is a comment. Change the following path to point to your Windows media file --> | Simple comment, in the same format as XML comments.
<REF HREF = "mms://YourServer/path/Yourfile.wma" /> | Actual pointer to the media file. The REF attribute identifies the line as a pointer to media content, while the HREF attribute is the URL to the media file. In this case, the URL uses the MMS protocol, so it points to a Windows Media Services server. Media files on your media server are not usually kept in the same location as your HTML documents. Note the use of the XML-like closing of the element , "/>", instead of "</REF>". Because this element does not have child elements, it closes itself.
</ENTRY> | Specifies the end of the of the ENTRY element.
</ASX> | Specifies the end of the playlist.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


An Advanced Playlist

The following playlist example shows how to use a more complete set of playlist elements. When writing your own code, you will need to change all URLs and file names to valid file names that are accessible to your Windows Media Player.

Example Code

<ASX version = "3.0">
    <TITLE>Advanced Playlist Demo</TITLE>
    <ABSTRACT>More Information at this Web site</ABSTRACT>
    <MOREINFO HREF="http://www.microsoft.com/windows/windowsmedia" />
    <BANNER HREF = "..\samples\home.gif">
        <ABSTRACT>MSN Web site</ABSTRACT>
        <MOREINFO HREF = "http://www.msn.com" />
    </BANNER>
    <PARAM name="track" value="1"/
    <ENTRY ClientSkip="no">
        <BANNER HREF = "..\sample\contact.gif">
            <ABSTRACT>Visit Our Web site</ABSTRACT>
            <MOREINFO HREF = "http://www.msn.com" />
        </BANNER>
        <MOREINFO HREF = "http://www.msn.com" />
        <!-- This is the ToolTip text for Title/Author/Copyright text -->
        <ABSTRACT>Visit the YourImage Web site</ABSTRACT>
        <TITLE>The first entry in an advanced playlist</TITLE>
        <AUTHOR>YourImage</AUTHOR>
        <COPYRIGHT>(c)2000 YourImage</COPYRIGHT>
        <!-- This is a comment.  Change the following path to point to
            your Windows Media file -->
         REF HREF =
           "..\media\laure.wma" />
    </ENTRY>

    <ENTRY>
        <TITLE>The second entry in the advanced playlist</TITLE>
        <AUTHOR>Microsoft Corporation</AUTHOR>
        <COPYRIGHT>(c)2000 Microsoft Corporation</COPYRIGHT>
        <!-- This is the ToolTip text for Title text -->
        <ABSTRACT>This is where you can include your tool tips</ABSTRACT>
        <!-- This is a comment.  Change the following path to point to
            your Windows Media file -->
        <REF HREF = ..\media\mellow.wma"
        />
    </ENTRY>
</ASX>

The following table describes the preceding advanced playlist.

Line | Description
<ASX version = "3.0"> | Identifier for the client (Windows Media Player) that this is a Windows Media metafile playlist. The VERSION attribute, specifies the version number of the metafile elements. .
<TITLE>Advanced Playlist Demo</TITLE> | Identifies the title of the playlist as a whole. Windows Media Player displays this metadata as the show title.
<ABSTRACT>More Information at this Web Site< /ABSTRACT> | The ABSTRACT element provides the ToolTip for the show title.
<MOREINFO HREF ="http://www.microsoft.com/windows/windowsmedia" > | The MOREINFO element links the show title to an URL. Pausing the mouse pointer over the show title accesses the ToolTip, if defined. Selecting the show title will then open the designated URL.
<BANNER HREF = "..\samples\home.gif"> | This creates an advertising BANNER in Windows Media Player. The HREF is the banner graphic, (194x32 pixels).
<ABSTRACT = "MSN Web site" | The ABSTRACT element provides the ToolTip for the BANNER.
</ABSTRACT> | Closes the ABSTRACT element
<MOREINFO HREF = "http://www.msn.com" </ABSTRACT> | The MOREINFO element links the BANNER graphic to a URL. Holding the mouse pointer over the BANNER accesses a ToolTip, if defined. Selecting the BANNER will open the designated URL.
<PARAM name = "track" value="1"/> | Defines a custom parameterfor the PARAM element. The NAME attribute defines the name of the custom parameter to be "track". The VALUE attribute defines the value of track to be "1".
</BANNER> | Closes the BANNER element
<ENTRY ClientSkip="no"> | Begins the ENTRY element block. This element defines a clip in a playlist by specifying a link in the REF element. Setting ClientSkip to "no" means that the user cannot fast forward or jump to the next clip
<BANNER HREF = "..\samples\contact.gif"> | Creates an advertising BANNER element. The HREF is the banner graphic (194x32 pixels).
<ABSTRACT>Visit Our Web site< /ABSTRACT> | The ABSTRACT element provides the ToolTip for the Banner.
<MOREINFO HREF = "http://www.msn.com" /> | The MOREINFO element provides a link to the URL for the banner. Selecting the banner connects to the URL.
</BANNER> | Closes the BANNER element
<MOREINFO HREF = "http://www.msn.com" /> | This MOREINFO element provides a link to the URL for the clip Title text.
<!--This is the ToolTip text for the Title text --> | A comment. This will only be visible when the code is viewed.
<Abstract>Visit the YourImage Web site</abstract> | This ABSTRACT element provides the ToolTip for the clip Title text.
TITLE>The first entry in an advanced playlist</TITLE> | Identifies the title of the clip. It is the clip TITLE because it is nested within an ENTRY element. Windows Media Player displays this metadata as the clip title.
<AUTHOR>YourImage</AUTHOR> | Identifies the author of the media clip. This metadata is displayed as the clip AUTHOR by Windows Media Player.
COPYRIGHT>(c)2000 YourImage</COPYRIGHT> | The COPYRIGHT element specifies the copyrights associated with the media clip. Windows Media Player displays this metadata as the clip COPYRIGHT.
<!-- This is a comment. Change the following path to point to your Windows Media file --> | A comment, in the same format as XML comments.
<REF HREF = "..\media\laure.wma" /> | URL for the media content. The REF element identifies the line as a pointer to media content. The HREF attribute is the URL to the file. Note the use of the XML-like closing of the element , "/>" instead of "</REF>". Because this element does not have child elements, it closes itself.
</ENTRY> | Specifies the end of the of the first ENTRY element.
<ENTRY> | Begins the second ENTRY element.
TITLE>The second Entry in a the advanced playlist</TITLE> | Identifies the title of the second clip.
<AUTHOR>Microsoft Corporation</AUTHOR> | Identifies the author of the second media clip.
COPYRIGHT>(c)2000 Microsoft Corporation</COPYRIGHT> | Specifies the copyright for the media clip.
<!--This is the ToolTip text for the Title/Author/Copyright text --> | A comment. It will only be visible when the code is viewed.
<ABSTRACT>This is where you can include your tool tips</ABSTRACT> | This is the ToolTip text for the Title text of the clip.
<!-- This is a comment. Change the following path to point to your Windows Media file --> | A comment. It will only be visible when the code is viewed.
<REF HREF = ..\media\mellow.wma" /> | Pointer to the media content. The REF attribute identifies the line as a pointer to media content. The HREF attribute is the URL to the file.
</ENTRY> | Specifies the end of the second ENTRY element.
</ASX> | Specifies the end of the playlist.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Elements Reference.
  • Windows Media Metafile Guide


An Example Radio Station Playlist

The following example code illustrates how to create a playlist to scan three rock radio stations. The psuedo company RadioNetwork brand is on the playlist and on all of the individual streams within the playlist. When you write your code, change all URLs and file names to valid file names that are accessible to your Windows Media Player.

A playlist is created for each of the stations. A fourth playlist scans through the first three. The playlists are created to reference dynamically generated advertisements and have RadioNetwork branding.

One of the playlists representing a radio station might look like this.

<ASX Version = "3.0">
    <Title>RADIONETWORK on RadioNetwork</title>
    <MoreInfo href = "http://www.RadioNetwork.tld/>
    <Entry ClientSkip = "no" SkiplfRef = "yes">
       <Ref href = "http://Myserver/ad.asp/>
    </Entry>
    <Entry>
        <Title>MyWRCK Radio </title>
        <Abstract>MyTown's Best Rock 'n Roll</abstract>
        <Copyright>2000 RadioNetwork,</copyright>
        <MoreInfo href = "http://www.RadioNetwork.tld"/>
        <Ref href = "http://Myserver/RadioNetwork.tld"/>
        <Ref href = "http://Mybackup/RadioNetwork.tld"/>
    </Entry>
</ASX>

The playlist can then be constructed of references to the individual playlists.

Example Code

<ASX Version = "3.0">
    <TITLE>RadioNetwork Top 3 Rock Stations</TITLE>
    <MOREINFO href = "http://www.RadioNetwork.tld/MyTop3Rocks"/>
    <REPEAT>
        <ENTRY ClientSkip = "no">
            <REF HREF = "http://Myserver/ad.asp/">
        </ENTRY>
        <DURATION VALUE="00:00:30" />
        <ENTRYREF  HREF = "http://www.RadioNetwork.tld/asx/RadioNetwork.wax"/>
        <DURATION VALUE="00:00:30" />
        <ENTRYREF HREF = "http://www.RadioNetwork.tld/asx/RadioNetwork2.wax/>
        <DURATION VALUE="00:00:30" />
        <ENTRYREF HREF = "http://www.RadioNetwork.tld/asx/RadioNetwork3.wax"/>
    </REPEAT>
</ASX>

This example would play an ad followed by 30 seconds of each of the three stations referenced, one after the other. This cycle will repeat indefinitely because the COUNT attribute of the REPEAT element is not defined.

The example companies, organizations, products, people and events depicted herein are fictitious. No association with any real company, organization, product, person or event is intended or should be inferred.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Metafile Extension Guidelines

A file name extension provides an independent software vendor (ISV) with information about the rendering requirements of an application that uses that particular extension, and enables content authors to target general types of players. For example, the .wma extension should be used for Jukebox-type applications.

Windows Media metafile extensions are used to identify the format of the Windows Media files that will be accessed. Windows Media metafiles that have .wax, .wvx, or .asx extensions access files with .wma (Windows Media Audio), .wmv (Windows Media Video), and .asf, (Windows Media file) extensions respectively. The metafiles will all have the ASX element tag at the beginning of the file, followed by "version" number. The .wma, .wmv, and .asf extensions identify the Windows Media compression technology used in creating the file.

The following table shows the media file types to be referenced by each type of metafile, .wax, .wvx, and .asx. The columns list media file extensions, the rows list metafile extensions. An X in a column indicates a media file type that can be referenced by a metafile with the file name extension in the leftmost column of that row.

Extension | asf | wma | wmv
wvx | X | X | X
wax | X | X |
asx | X |  |

See Also

  • File Name Extensions
  • Windows Media Metafile Guide


Order of Precedence

Not all metafile element attributes are created equal. Some metafile element attributes override other element attributes. Element attributes can be overridden by similar element attributes depending on position and order. Any attributes of a metafile playlist override those contained in a referenced Windows Media file. An attribute that overrides another has higher precedence.

The hierarchy, highest precedence to lowest, is shown in the following table. The highest precedence item is never overridden.

Scope | Hierarchy
"Signed DRM content" | Never overridden.
REF element scope | Only overridden by signed DRM content.
ENTRY element scope | Overrides elements of the categories below.
ASX scope | Overrides media file elements.
Windows Media file scope | Overridden by all of the above.

  • "Signed DRM content" - Digital signature object.

    Attributes of Signed DRM content will override all others. For example, the Copyright information of "Signed DRM content" will not be overridden. It will always be streamed and presented.

  • REF element scope

    Attributes of the REF element will override other element attributes, but not signed DRM content.

  • ENTRY scope

    Attributes of the ENTRY element will be overridden by the REF element attribute but will override other element attributes. TITLE metadata from the ENTRY element is displayed instead of the title information from the media file.

  • ASX scope

    Any properties that are entered in the metafile override those contained in the Windows Media file. Attributes of the ENTRY element override ASX element attributes. While the ENTRY element's referenced media clip is playing, TITLE metadata from the ENTRY element is displayed instead of title information from the ASX element.

  • Windows Media file scope

    Attributes of the Windows Media file are overridden by any metafile attributes. Media file metadata is displayed only if there is no metadata defined for that element in the metafile.

See Also

  • Creating Metafile Playlists
  • Metafile Playlists
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide


Windows Media Metafile Reference

This reference documents elements and file extensions for Windows Media metafiles. The reference is divided into the following sections.

Section | Description
Windows Media Metafile Elements Reference | Documents metafile elements, including definitions, attributes and their values, and special conditions related to each element.
File Name Extensions | Documents metafile file name extensions with rules and guidelines on their use.

Windows Media metafiles are text files that provide information about a file stream and its presentation. The metafiles are based on the Extensible Markup Language (XML) syntax, and are made up of various XML-like elements with their tags and attributes. Each element defines a setting or action for streaming media.

There are two sets of element tags available for metafiles. Client-side metafiles have one set of elements, and server-side metafiles have another set of elements.

If an element tag does not have any child elements (those that modify or are contained within another element), a single slash character (/) can be used at the end of the opening tag in place of a closing tag. If child elements do not appear between the opening and closing tag for an element, they are not child elements for that element, and are ignored or cause an error in the syntax of the metafile.

See Also

  • About Windows Media Metafiles
  • Windows Media Metafile Guide


Windows Media Metafile Elements Reference

This section contains reference documentation for all Windows Media metafile elements for client-side applications. Reference entries include definitions of the elements, their attributes and values, and special conditions related to each element.

The following metafile elements are supported for client-side applications.

Element | Description
ABSTRACT | Contains text that describes the associated ASX, BANNER, or ENTRY element.
ASX | Defines a file as a Windows Media metafile.
AUTHOR | Contains the name of the author of a media clip or a Windows Media metafile.
BANNER | Specifies a URL for a graphic that appears in the display panel of Windows Media Player.
BASE | Specifies a string that is appended to the front of URLs sent to Windows Media Player.
Comments | Specifies the XML syntax for comments ( <!--...--> ).
COPYRIGHT | Contains the copyright information for an ASX or ENTRY element.
DURATION | Specifies the length of time Windows Media Player renders a stream.
ENDMARKER | Specifies a marker at which Windows Media Player stops rendering the stream.
ENTRY | Specifies the path for a media clip.
ENTRYREF | Links to the ENTRY elements in an external Windows Media metafile that has an .asx, .wax, .wvx, or .wmx extension.
EVENT | Defines a behavior or action taken by Windows Media Player when it receives a script command labeled as an event.
LOGO | Specifies a graphic file to be displayed as a logo. Not supported in Windows Media Player after version 6.4.
LOGURL | Instructs the player to submit any log data to the specified URL.
MOREINFO | Specifies a URL for a Web site, e-mail address, or script command associated with a show, clip, or banner.
PARAM | Specifies the value of a custom parameter associated with a clip.
PREVIEWDURATION | Specifies the length of time a clip is played in preview mode.
REF | Specifies a URL for a piece of media content.
REPEAT | Specifies the number of times Windows Media Player repeats one or more ENTRY or ENTRYREF elements.
SKIN | Specifies a URL to an embedded skin. This element is supported only for Windows Media Player 7 or later.
STARTMARKER | Specifies a marker at which Windows Media Player starts rendering the stream.
STARTTIME | Specifies a time at which Windows Media Player will start rendering the stream.
TITLE | Contains the title of an ASX or ENTRY element.

See Also

  • Windows Media Metafile Reference


ABSTRACT Element

The ABSTRACT element contains text that describes the associated ASX, BANNER, or ENTRY element.

Syntax

<ABSTRACT>
   text string
</ABSTRACT>

Attributes

None.

Parent/Child Elements

Hierarchy | Elements
Parent | ASX, ENTRY, BANNER
Child | None

Remarks

If this element appears within an ASX element, the text displays as a ToolTip when the mouse hovers over the show title. In Windows Media Player version 6.4, the text also appears in the Show tab of the Properties dialog box, under Description.

If this element appears within an ENTRY element, the text displays as a ToolTip when the mouse hovers over the clip title. In Windows Media Player version 6.4, the text also appears in the Clip tab of the Properties dialog box, under Description.

If this element appears within a BANNER element, the text is displayed as a ToolTip for the banner graphic.

Use only one ABSTRACT element per scope. Only the first ABSTRACT element within a the scope of another element is used when a metafile file is processed. Any subsequent ABSTRACT elements in that scope are ignored.

Example Code

<ASX VERSION="3.0">
    <TITLE>The Title of the Show<TITLE>
    <ABSTRACT>
        Brief description of the show.
    </ABSTRACT>

<ENTRY>
    <REF HREF="YourMediaFilename.asf" />
    <TITLE>The Title of the Track</TITLE>
    <ABSTRACT>
        Brief description of the track.
    </ABSTRACT>
</ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


ASX Element

The ASX element defines a file as a metafile.

Syntax

<ASX
   VERSION="number"
   PREVIEWMODE= "YES" | "NO"
   BANNERBAR= "AUTO" | "FIXED"
>
</ASX>

Attributes

VERSION (required)

Decimal number representing the version number of the syntax for the metafile Set to 3 or 3.0.

PREVIEWMODE

Value indicating whether the Windows Media Player control enters preview mode before playing the first clip.

Must be one of the following values..

Value | Description
YES | The Windows Media Player control enters preview mode before playing the first clip.
NO | The default value. The Windows Media Player control does not enter preview mode before playing the first clip.

BANNERBAR

Value indicating whether the Windows Media Player control reserves space for a banner graphic.

Must be one of the following values.

Value | Description
AUTO | The default value. The Windows Media Player control reserves space for the banner bar only when a piece of content includes one.
FIXED | The Windows Media Player control reserves a fixed space for a banner graphic for every piece of content played, whether or not there is an associated banner.

Parent/Child Elements

Hierarchy | Elements
Parent elements | None. The ASX element must be the first element in every metafile.
Child elements | ABSTRACT, AUTHOR, BANNER, BASE, COPYRIGHT, ENTRY, ENTRYREF, EVENT, LOGO, MOREINFO, PREVIEWDURATION, PARAM, REPEAT, TITLE

Remarks

The first four characters of a metafile playlist must be <ASX. Other elements defined within the scope of the ASX element, such as TITLE and AUTHOR, are associated with the show information displayed by Windows Media Player.

For Windows Media Player, the syntax version number is 3.0. Windows Media Player supports all previous versions of metafile syntax. Acceptable values for the VERSION attribute include both 3.0 and 3 (with no decimal point).

If the value of the PREVIEWMODE attribute is YES, the Windows Media Player control immediately enters preview mode before playing the first clip. When Windows Media Player enters preview mode, it previews each clip referenced in the metafile. The PREVIEWDURATION element determines the duration of each preview.

The BANNERBAR attribute defines whether the Windows Media Player control reserves space for a banner graphic. A banner is a graphic that is displayed in the video display area while media content is playing. (Use the BANNER element to add a banner to the content.) If the value of BANNERBAR is FIXED, Windows Media Player reserves banner space for every piece of media content, whether or not the media content has a banner. If a piece of media content does not have a banner associated with it, the space reserved for one is black. If the value of the BANNERBAR attribute is AUTO, Windows Media Player reserves space for the banner only when the media content includes one.

If you create a metafile with multiple clips (ENTRY or ENTRYREF elements) and set the value of the BANNERBAR attribute to AUTO, the Windows Media Player control might resize to allow space for a banner graphic for one clip, and then resize again if the next clip does not contain a banner graphic. If you want the size of the window to stay the same (except when the video size changes), use the FIXED value for the BANNERBAR attribute.

The space reserved for a banner graphic is 32 pixels high by 194 pixels wide. The reserved space appears below any rendered video content and 6 pixels above the lower edge of the video area, allowing space for the 6-pixel video area border. The reserved banner space is centered horizontally.

Window Media Player version 6.4 centers the rendered graphic horizontally.

Windows Media Player 7 or later renders the graphic beginning in the leftmost pixel of the banner space. If the graphic fills the entire space, it will appear centered horizontally. Otherwise there will be trailing space. Note that the minimum width of the Windows Media Player control is always wider than the size of the video clip, regardless of the value of the BANNERBAR attribute.

Example Code

<ASX VERSION="3.0" PREVIEWMODE="YES" BANNERBAR="auto"  >
   <ENTRY HREF="http://samples.microsoft.com/sample1.ASX />
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


AUTHOR Element

The AUTHOR element contains the name of the author of a Windows Media metafile or media clip.

Syntax

<AUTHOR>
   text string
</AUTHOR>

Attributes

None.

Parent/Child Elements

Hierarchy | Element
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element contains a text string representing the name of the author of a Windows Media metafile or media clip. You can use the AUTHOR element within the ASX element and within ENTRY elements.

If this element appears in the ASX element, the text is displayed as Show information. In Windows Media Player version 6.4, the text also appears in the Show tab of the Properties dialog box.

If this element appears in an ENTRY element, the text is displayed as the clip author. In Windows Media Player version 6.4, the text also appears in the Clip tab of the Properties dialog box.

Each parent ASX and ENTRY element should contain at most one child AUTHOR element. Multiple AUTHOR elements after the first will be ignored and will not be displayed.

Example Code

<ASX VERSION="3.0">
   <AUTHOR>Neal S.</AUTHOR>   <!-- Show author -->
   <ENTRY>
      <REF HREF="mms://example.microsoft.com/clip1.asf" />
      <AUTHOR>Robert P.</AUTHOR>  <!-- Clip author -->
   </ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


BANNER Element

The BANNER Element defines a URL to a graphic file that will appear in the display panel.

Syntax

<BANNER
   HREF="URL"
</BANNER>

Attributes

HREF (required)

URL to a graphic file that is displayed in the display panel.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | ABSTRACT, MOREINFO

Remarks

This element defines a URL to a graphic file that appears in the Microsoft® Windows Media™ Player control's display panel, beneath the video content. If the media is audio only, the banner graphic is displayed by itself. The Windows Media Player control reserves a space 32 pixels high by 194 pixels wide (the banner bar) for the graphic. If the graphic defined in the URL is smaller than that, it displays at its original size. If the graphic is larger than the reserved space, the Windows Media Player control will crop the image to fit the space.

You can use an ABSTRACT element within the scope of the BANNER element to display text as a ToolTip when the user pauses the mouse pointer over the banner graphic. A MOREINFO element within a BANNER element defines a URL to which the user is taken when the user clicks the banner graphic. (The URL can be any path or protocol, such as an e-mail link, a Hypertext Transfer Protocol (HTTP) URL to a Web site, or even a Microsoft® JScript® command.) When the pointer is moved over the graphic, the graphic becomes embossed and looks like a button.

A BANNER element defined for an ASX element displays while all clips in the playlist are playing. A BANNER element defined in an ENTRY element displays only while that clip is playing, and during that time overrides any banner defined within the parent ASX element. You can specify how Windows Media Player reserves space for the banner by setting the BANNERBAR attribute of the ASX element.

Banner images are not supported with DRM files or when the player is embedded in a Web page.

Example Code

The following is an example of a BANNER element without child elements:

<BANNER HREF="http://samples.microsoft.com/art/banner1.bmp" />

The following is an example of a BANNER element containing ABSTRACT and MOREINFO elements.

<BANNER HREF="http://www.servername.com/logos/banner1.bmp">
    <ABSTRACT>Click here to go to our Web site.</ABSTRACT>
    <MOREINFO HREF="http://samples.microsoft.com" />
    <!-- The text in the Abstract element displays as a
         ToolTip when the mouse hovers over the banner
         graphic. When a user clicks the banner, the URL
         given in the MoreInfo element opens in the
         browser. -->
</BANNER>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


BASE Element

The BASE element defines a URL string appended to the front of URLs sent to the Microsoft® Windows Media™ Player control.

Syntax

<BASE
   HREF="URL"
/>

Attributes

HREF (required)

The string appended to the front to URLs sent to the Windows Media Player control. The default value is the null string ("").

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element defines a Uniform Resource Locator (URL) string appended to the front of URL-flip URLs sent to the Windows Media Player control. URL-flipping is a scripting mechanism that causes Windows Media Player to open a new URL in a browser or browser frame when it receives a script command.

The BASE element is similar to a home directory for relative links. It only affects URLs sent using script commands as part of the content stream that is playing in Windows Media Player.

A BASE element defined as the child of an ASX element becomes the default for the entire metafile. A BASE element defined in an ENTRY element overrides any BASE element in the parent ASX element (for that ENTRY element only).

Note If the HREF attribute does not end with a / character, Windows Media Player appends one to the end of the string.

Example Code

<BASE HREF="http://msdn.microsoft.com/" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


Comments

Add comments to metafiles by following Extensible Markup Language (XML) syntax. Comments begin with "<!--" and end with " -->".

Syntax

<!--Enter your comment text here.-->

Remarks

Comments can appear anywhere except within element content (between element open and close tags, < >). They are not part of the document's character data and are ignored when the metafile is parsed.

Windows Media Player version 6.4 will parse, recognize and implement metafile element tags within comment tags. When including metafile element tags within comment tags for Windows Media Player version 6.4 there must be no spaces or line breaks after the opening comment tag, <!--, and no spaces or line breaks before the ending comment tag, -->. This only applies to commenting out a set of element tags, <!--<BANNER> ... </BANNER>-->

The element tags within the comment tags would not be implemented in Windows Media Player version 7 or later. They would be effectively commented out by the comment tags.

Example Code

<ASX version = "3.0">
<!-- This information is only visible when editing a metafile file. -->
<!-- The following effort to comment out the BANNER will not work for Windows Media Player version 6.4. Windows Media Player version 6.4 would still parse the BANNER element and display the graphic.-->
<!--<BANNER HREF="c:\wmsdk\wmssdk\samples\dhtml\asfbutton3.gif">
    </BANNER>-->
    <ENTRY>
        <REF HREF = "mms://nsserver/pubpt/filename.asf" />
    </ENTRY>

    <ENTRY>
        <TITLE>WMA Port na Pucai</TITLE>
<!-- For Windows Media Player version 6.4, the DURATION VALUE will still be parsed and the media rendered for 15 seconds.-->
        <!--<DURATION VALUE="00:00:15"/>-->
        <REF href="c:\asfroot\Port na Pucai.wma"/>
    </ENTRY></ASX>


Adding Copyright Characters to Metafiles

The characters for copyright or trademark registration symbols ( © or ® ) do not display properly with all international character sets. To display either of these symbols properly for all users, you should use the ASCII equivalents (c) or (r) inside the COPYRIGHT element, as shown in the following code.

<COPYRIGHT>Copyright (c)1998, Microsoft Corporation</COPYRIGHT>


COPYRIGHT Element

The COPYRIGHT element defines a text string specifying the copyright information for an ASX or ENTRY element.

Syntax

<COPYRIGHT>
   text string
</COPYRIGHT>

Attributes

None.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element defines a text string that specifies the copyright information for an ASX or ENTRY element.

When this element appears within an ASX element, the copyright string is displayed only as Show information.

For Windows Media Player version 6.4 the copyright information also appears in the Show Properties dialog box. When this element appears within an ENTRY element, the text is displayed as clip information. For Windows Media Player version 6.4 the Clip copyright information also appears on the Clip tab of the Properties dialog box.

Each parent ASX and ENTRY element should contain at most one child COPYRIGHT element. Multiple COPYRIGHT elements after the first will be ignored and will not be displayed.

The characters for copyright or trademark registration symbols ( © or ® ) do not display properly with all international character sets. To display either of these symbols properly for all users, you should use the ASCII equivalents (c) or (R) instead.

Example Code

<COPYRIGHT>Copyright (c)1998, Microsoft Corporation</COPYRIGHT>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


DURATION Element

The DURATION element defines the length of time the Windows Media Player control will render a stream.

Syntax

<DURATION
   VALUE="hh:mm:ss.fract"
/>

Attributes

VALUE (required)

The length of time, in hours, minutes, seconds, and hundredths of a second, that a stream is rendered by the Windows Media Player control. The default value is the entire length of the content stream or media clip.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ENTRY, REF
Child elements | None

Remarks

This element defines the length of time a stream is to be rendered. If the VALUE attribute exceeds the length of the content stream, the stream terminates at its normal end-point.

This element can appear either within a REF element or within an ENTRY element. However, a DURATION element defined within a REF element overrides one that appears within the REF element's parent ENTRY element.

The DURATION element overrides a PREVIEWDURATION element.

Example Code

<DURATION VALUE="00:00:30" />   <!-- 30 seconds -->
<DURATION VALUE="1:01.5" />     <!-- 61.5 seconds -->

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


ENDMARKER Element

The ENDMARKER element specifies a marker at which the Windows Media Player control will stop rendering the stream.

Syntax

<ENDMARKER
   NUMBER="marker number" |
   NAME="marker name"
/>

Attributes

NUMBER

The number of a numeric marker in the index. The default value is the end of the content.

NAME

The name of a named marker in the index. The default value is the end of the content.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ENTRY, REF
Child elements | None

Remarks

This element specifies the marker where the Windows Media Player control is to stop rendering the stream defined in the parent ENTRY or REF element.

Note Use the ENDMARKER element with either the NUMBER or NAME attribute, but not both.

In preview mode, reaching an end marker stops the preview, even if the time specified by the PREVIEWDURATION element has not elapsed. The ENDMARKER element also takes precedence over the DURATION element.

An ENDMARKER element defined within a REF element takes precedence over an ENDMARKER defined within the REF element's parent ENTRY element.

If the marker specified by an ENDMARKER element occurs earlier in the stream than the marker defined by a STARTMARKER element, no content plays, but no error is generated.

Example Code

<ENDMARKER NUMBER="17" />
<ENDMARKER NAME="Marker_StopHere" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


ENTRY Element

The ENTRY element specifies a Windows Media file to render as a clip.

Syntax

<ENTRY
   CLIENTSKIP= "YES" | "NO"
   SKIPIFREF= "YES" | "NO"
>
</ENTRY>

Attributes

CLIENTSKIP

Value indicating whether the user can skip forward past the clip.

Possible values include the following.

Value | Description
YES | Default. User can skip forward past the clip.
NO | User cannot skip forward past the clip.

SKIPIFREF

Value indicating whether the Microsoft® Windows Media™ Player control should skip this clip when the ENTRY element is included in a second Metafile through the use of an ENTRYREF element.

Possible values include the following.

Value | Description
YES | Windows Media Player will ignore this entry, if referenced through an ENTRYREF element.
NO | Default. Windows Media Player will not ignore this entry.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, EVENT, REPEAT
Child elements | ABSTRACT, AUTHOR, BANNER, BASE, COPYRIGHT, DURATION, ENDMARKER, LOGO, MOREINFO, PARAM, PREVIEWDURATION, REF, STARTMARKER, STARTTIME, TITLE

Remarks

This element is the fundamental construct in a Windows Media metafile. The ENTRY element and its associated attributes define meta-information for a single, logical piece of content, called a clip. Child elements within the scope of an ENTRY element define media content for the Windows Media Player control to open (REF), information about the clip that Windows Media Player will display as text (AUTHOR, COPYRIGHT, TITLE), and other settings related to the clip. The REF child element links the content to be streamed for the parent ENTRY element. Though the script will not break, the ENTRY is meaningless without a REF child.

If the value of the CLIENTSKIP attribute is NO, the user cannot skip forward past the piece of content defined by the ENTRY element.

The SKIPIFREF attribute pertains only to ENTRY elements that are included in a second Metafile through the use of an ENTRYREF element. The ENTRYREF element references another metafile for logical inclusion in the current file. If the value of the SKIPIFREF attribute for an ENTRY element from the referenced metafile file is YES, Windows Media Player ignores this pulled-in entry, and moves on to the next ENTRY element, if any. The next ENTRY element can be the next entry in the original file, or the next entry in the metafile referenced in the ENTRYREF element.

Example Code

<ASX VERSION="3.0">
   <TITLE>Example Windows Media Player Show</TITLE>

   <ENTRY>
      <TITLE>Example Clip</TITLE>
      <REF HREF="http://example.microsoft.com/media.asf" />
   </ENTRY>

   <ENTRY>
      <TITLE>Another Clip</TITLE>
      <REF HREF="http://example.microsoft.com/more_media.asf" />
   </ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


ENTRYREF Element

The ENTRYREF element points to the ENTRY elements in an external metafile.

Syntax

<ENTRYREF
   HREF="URL"
/>

Attributes

HREF (required)

URL to a referenced Metafile.

CLIENTBIND

This attribute is no longer supported.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, EVENT, REPEAT
Child elements | None

Remarks

This element points to the contents of an external metafile. The Windows Media Player control processes the ENTRY elements of the referenced metafile as if they were included in the primary metafile at the position of the ENTRYREF element. However, it skips any ENTRY elements in the referenced metafile that have the SKIPIFREF attribute set to YES.

The Windows Media Player control ignores any ENTRYREF elements in the referenced metafile. Thus, metafiles can only be nested one level deep. Windows Media Player also ignores the ASX element in the referenced file along with its attributes.

If a user adds a Favorites entry to a piece of content defined in the included metafile, Windows Media Player uses the URL to the metafile referenced in the ENTRYREF element.

Example Code

<ASX VERSION="3.0">
   <TITLE>Example of Using EntryRef</TITLE>
   <ENTRYREF HREF="http://samples.microsoft.com/metafile.asx" />
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


EVENT Element

The EVENT element defines a behavior or action taken by Windows Media Player when it receives a script command labeled as an event.

Syntax

<EVENT
   NAME="text string"
   WHENDONE= "RESUME" | "NEXT" | "BREAK"
>
</EVENT>

Attributes

NAME (required)

The value of the event as created in Windows Media Author.

WHENDONE (required)

Value that defines what Windows Media Player does after playing the referenced content.

The following values are possible.

Value | Description
RESUME | The current entry (the clip interrupted by the event) resumes playing. If the content is stored content, it resumes at the same point where it stopped; if the content is broadcast, it resumes at the current position.
NEXT | The next ENTRY element plays as if the event had not occurred and Windows Media Player had reached the end of the current clip.
BREAK | If the current entry is within a REPEAT loop, the loop terminates as if the repeat count had been completed. Otherwise, Windows Media Player jumps to the end of the playlist as if the final entry had completed as usual.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX
Child elements | ENTRY, ENTRYREF

Remarks

This element defines a behavior or action taken by the Windows Media Player control when it receives a script command labeled as an event. An event is a particular type of script command embedded in a stream sent to Windows Media Player that consists of a double string. The first string is the word "event", and the second string is the event name. The event name in the second string must match the event name defined in the metafile. (The match is not case-sensitive.) Events can be sent to a Windows Media Player control receiving a real-time stream, or can be saved in a file with an .asf, .wma, or .wmv extension, that gets delivered as an on-demand unicast stream. When the Windows Media Player control receives the script command, it processes the event as defined by the EVENT element.

This element defines a scope of ENTRY or ENTRYREF elements that are processed whenever the Windows Media Player control receives the script command with the named event. The ENTRYREF can be a URL that points to an ASP page. With this element, you can specify a behavior for stream switching in near real-time, as opposed to pre-authored stream changes using references to other pieces of content or Windows Media metafiles.

When you use ASP pages to generate playlists, you must define a Response-type variable, as well as a Response-expire variable in the ASP page because of latency issues with Windows Media Player. The response type must be a valid extension for Windows Media metafiles. Valid types include asf, asx, wma, wax, wmv, and wvx.

This element can appear anywhere within the ASX element. If multiple EVENT elements within an ASX element have identical values for their NAME attributes, the Windows Media Player control uses the first occurrence within the ASX element, and ignores all others. When EVENT elements have distinct NAME attributes, their order within the ASX element does not matter.

The Windows Media Player control discards events it receives while processing another event. Nesting of events is not supported. When the Windows Media Player control is in preview mode, event content is not constrained by the PREVIEWDURATION element; the full length of event content can play even if the preview duration for the active ENTRY element expires prior to the end of the event.

Example Code

In this example, when Windows Media Player receives the script command EVENT and command string "Adlink" in the streaming media it is rendering, it searches the playlist for an EVENT NAME "Adlink". Windows Media Player switches from the stream it is rendering and plays the content referenced in the EVENT, "http://example.microsoft.com/adlink.htm".

ENTRY attribute CLIENTSKIP is set to NO to prevent the EVENT clip from being skipped. It must be played.

<ASX VERSION="3.0">
<ENTRY CLIENTSKIP="NO">
   <REF HREF="http://example.microsoft.com/clip1.asf" />
</ENTRY>
<EVENT NAME="Adlink" WHENDONE="RESUME">
   <ENTRYREF HREF="http://example.microsoft.com/adlink.htm"
       CLIENTSKIP="NO" />
</EVENT>
</ASX>

The script WHENDONE="RESUME" instructs Windows Media Player to resume playing the previous media it switched from as soon as Adlink.asf is finished.

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference
  • Windows Media Player ActiveX Control


LOGO Element

The LOGO element specifies a graphic file to display as a logo.

Not supported after Windows Media Player version 6.4.

Syntax

<LOGO
   HREF="URL"
   STYLE= "ICON" | "MARK"
/>

Attributes

HREF (required)

Specifies the URL to a graphic file that will display as a logo.

STYLE (required)

Specifies how the logo is displayed. It must be one of the following values.

Value | Description
ICON | The logo appears as a 16 pixel by 16 pixel icon on the display panel, next to the title of the show or clip.
MARK | The logo appears in the lower-right corner of the video area while the Microsoft Windows Media Player control is connecting to a server and opening a piece of content. The logo display area is 32 pixels high and 80 pixels wide.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element specifies a graphic file to display as a logo. The logo is associated either with a single clip (when the LOGO element is the child of an ENTRY element) or with an entire show (when the LOGO element is the child of an ASX element). The logo's appearance depends on the value of the STYLE attribute.

If the STYLE attribute equals ICON, the logo replaces the icon that appears on the display panel next to the show title or clip title. (Normally, this is the icon associated with the file or stream type.) An ICON-style logo is displayed for the duration of the clip when associated with an ENTRY element, and for the duration of the entire show when associated with an ASX element.

If the STYLE attribute equals MARK, the logo appears in the lower-right corner of the video area (allowing for a six-pixel border) while Windows Media Player is connecting to a server and opening a piece of content. The graphic is not displayed after the content begins playing. A MARK-style logo must be associated with a show, not a clip (that is, the LOGO element must be the child of an ASX element rather than an ENTRY element).

Windows Media Player supports the ICO graphic format for icons.

Example Code

<LOGO HREF="http://samples.microsoft.com/art/logo1.gif" STYLE="ICON" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


LOGURL Element

Instructs the player to submit any log data to the specified URL.

Syntax

<LOGURL
   HREF="URL"
/>

Attributes

None

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

The LOGURL element enables a client metafile playlist to post log statistics to the origin server and any specified location on the Web.The URL must be to a host that is able to process logging requests. The URL can be any valid HTTP URL. The URL can also be to some CGI script.

The only valid protocols for a LOGURL element are HTTP and HTTPS.

An ASX scope LOGURL element in a metafile playlist referenced from another metafile playlist will be limited to the scope of that referenced file. A LOGURL element forces the submission of log data for all content streamed from within its defined scope and only for content streamed from within its defined scope. Log data will be submitted to the origin server and to all URLs listed in every LOGURL element in scope. Log data will be submitted only once to each listed URL, even if the same URL is listed more than once in a given scope. A repeat of an ENTRY would result in another submission to the listed URLs.

There is no limit to the number of LOGURL elements in a metafile playlist.

Example Code

<ASX VERSION="3.0">
  <TITLE>Example Media Player Show</TITLE>
  <LOGURL HREF="http://example.microsoft.com/info/showlog.asp?whatsup" />
  <ENTRY>
    <REF href="mms://ucast.blah.com/Media1.asf" />
    <LOGURL HREF="http://foobar.com/cgi-bin/logging.pl?SomeArg=SomeVal"/>
  </ENTRY>
</ASX>

The following are valid URLs.

An URL to An ISAPI application:

http://www.foo.com/logs/WMSLogging.dll

An URL to some CGI script:

http://www.foo.com/cgi-bin/My_WMS_Logging_Script.pl

Any valid HTTP URL:

http://www.foo.com/some/arbitrary/path/My_WMS_Logging_Page.asp?PubPoint=FooPubPoint&AnotherName=AnotherValue

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


MOREINFO Element

The MOREINFO element specifies a URL to a Web site, e-mail address, or script command associated with a show, clip, or banner.

Syntax

<MOREINFO
   HREF="URL"
   TARGET="Frame"
/>

Attributes

HREF (required)

URL to a Web site, e-mail address, or script command.

TARGET

Value defining the frame or window in which the browser will open the page defined by the HREF attribute.

This can be a string containing a window name, or one of the following values.

Value | Description
_blank | The document loads in a new browser window.
_self | The document loads in the same frame as the current document containing the Windows Media Player control.
_parent | The document loads in the immediate parent frame of the current frame, or the current frame if there is no parent frame.
_top | The document loads in the full browser window, replacing all other frames or documents.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY, BANNER
Child elements | None

Remarks

This element specifies a URL to a Web site, e-mail address, or script command. The user can access the target of the URL by clicking on the graphic or text associated with the MOREINFO element, or, for Windows Media Player version 6.4, by opening the More Information submenu of the Windows Media Player File menu. The details depend on the parent element of the MOREINFO element:

  • If the MOREINFO element is the child of an ASX element, the user can access the URL by clicking the show title, or, for Windows Media Player version 6.4, by choosing Show from the More Information submenu.
  • If the MOREINFO element is the child of an ENTRY element, the user can access the URL by clicking the clip title, or, for Windows Media Player version 6.4, by choosing Clip from the More Information submenu.
  • If the MOREINFO element is the child of a BANNER element, the user can access the URL by clicking the banner graphic, or, for Windows Media Player version 6.4, by choosing BANNER from the More Information submenu.

If the HREF attribute specifies a URL to a Web site, the browser opens and navigates to the URL. If the HREF attribute specifies an e-mail address, the user's e-mail application starts. If the HREF attribute specifies a script command, the script command executes in the browser.

Note If the MOREINFO element appears within an ASX or ENTRY element, when the mouse cursor is held over the title of the show (for an ASX element) or clip (for an ENTRY element), the URL defined in the HREF attribute can be selected and accessed by Windows Media Player.

The TARGET attribute defines the frame or window in which the browser will open the page defined by the HREF attribute. The values for this attribute follow standard HTML syntax and definitions. In the case of a control embedded in a Web page, if no TARGET attribute is defined, the URL loads the current browser window and replaces the existing page, which means the content stops playing. Therefore, it is recommended that you always specify a TARGET attribute when embedding the Windows Media Player control in a Web page.

If the metafile is opened in the stand-alone Windows Media Player, the TARGET attribute is ignored, and the URL loads in a new browser window.

Example Code

<ASX VERSION="3.0">

   <TITLE>Example Media Player Show</TITLE>
   <MOREINFO HREF="http://example.microsoft.com/info/show_info.htm" />

   <ENTRY>
      <TITLE>Example Clip</TITLE>
      <MOREINFO HREF="http://example.microsoft.com/info/clip1_info.htm" />
      <REF HREF="mms://example.microsoft.com/media.asf" />
   </ENTRY>

</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


PARAM Element

The PARAM Element defines a custom parameter associated with a clip or show.

Syntax

<PARAM
   NAME="parameter name"
   VALUE="parameter value"
/>

Attributes

NAME

Name used to access the parameter value. The name can be any valid string.

VALUE

Value associated with this parameter. It can be either a numeric or string value.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element allows users to place additional information about each clip inside the ENTRY element that contains it. To retrieve metadata information specified in the playlist ENTRY for Windows Media Player 7 or later, use the Media.getItemInfo method. The Media.getItemInfo method retrieves the value of the VALUE attribute, given the name of the parameter. retrieve metadata information specified in the playlist ENTRY, using the GetMediaParameter method given the name of the parameter and an index number for the entry.

A parameter can also be associated with the show rather than an individual clip, by placing this element directly after the ASX tag. These items are referenced by their names and an index value of zero.

Note This ASX element is only available for Windows Media Player version 6.01 and later. The standard installation of Microsoft Internet Explorer 5 includes a compatible version of Windows Media Player.

Example Code

<ASX VERSION="3.0">
   <TITLE>Example Media Player Show</TITLE>
   <PARAM NAME="Director" VALUE="Jane D." />

   <ENTRY>
      <TITLE>Example Clip</TITLE>
      <REF HREF="http://samples.microsoft.com/media.asf" />
      <PARAM NAME="Location" VALUE="North America" />
      <PARAM NAME="Release Date" VALUE="March 1998" />
   </ENTRY>

   <ENTRY>
      <TITLE>Another Clip</TITLE>
      <REF HREF="http://samples.microsoft.com/more_media.asf" />
      <PARAM NAME="Location" VALUE="Japan">
      <PARAM NAME="Release Date" VALUE="December 1996" />
   </ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


PREVIEWDURATION Element

The PREVIEWDURATION element defines the length of time a clip plays in preview mode.

Syntax

<PREVIEWDURATION
   VALUE="hh:mm:ss.fract"
/>

Attributes

VALUE (required)

Length of time, in hours, minutes, seconds, and hundredths of seconds, that the clip plays in preview mode.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY, REF
Child elements | None

Remarks

This element defines the length of time that a clip plays in preview mode. If this element appears within an ENTRY element or a REF element, it applies to the clip defined by that element. If it appears within the scope of an ASX element, it applies to every clip in the metafile. A PREVIEWDURATION element in a REF element takes precedence over one in an ENTRY element, and either takes precedence over a PREVIEWDURATION element in an ASX element. If no PREVIEWDURATION element is defined for a clip, the default preview time is 10 seconds.

If there is a STARTTIME or STARTMARKER element for the clip, the Windows Media Player control renders the clip starting at the point defined by one of these elements; otherwise it renders from the beginning of the clip. The clip stops normally if it is shorter than the time defined by the PREVIEWDURATION element.

The DURATION element overrides a PREVIEWDURATION element.

Example Code

<PREVIEWDURATION VALUE="0:30.0" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


REF Element

The REF element specifies a URL for a piece of media content.

Syntax

<REF
   HREF="URL"
>
</REF>

Attributes

HREF (required)

URL to any piece of media content supported by Microsoft Windows Media Player.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ENTRY
Child elements | DURATION, ENDMARKER, PREVIEWDURATION, STARTMARKER, STARTTIME

Remarks

This element specifies a URL for a piece of media content. The URL can point to any media type supported, using any protocol supported by Windows Media Player. The most common use of this element is for URL rollover. If Windows Media Player is unable to open a piece of media defined in a REF element, it tries the URL in the next REF element. Once Windows Media Player opens media content from a URL defined within the scope of one ENTRY element, it ignores subsequent REF tags within that ENTRY element. After the piece of content is done playing, Windows Media Player moves on to the next ENTRY element, if any.

Important Once Windows Media Player establishes a connection to a referenced piece of content, it ignores all other REF elements in that ENTRY, whether the connection terminates normally or abnormally.

To use compact disc audio with your CD-ROM drive as input to the Windows Media Player control, specify cdaudio: (with the trailing ":") as the HREF value.

Example Code

<ASX VERSION="3.0">
   <ENTRY>
   <TITLE>Example Clip</TITLE>
      <REF HREF="mms://example.microsoft.com/selection1.asf" />
      <REF HREF="mms://samples.microsoft.com/mirror/selection1.asf" />
   </ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


REPEAT Element

The REPEAT element defines the number of times the Windows Media Player control repeats one or more ENTRY or ENTRYREF elements.

Syntax

<REPEAT
   COUNT="integer"
>
</REPEAT>

Attributes

COUNT

Integer representing the number of times Windows Media Player repeats the ENTRY and ENTRYREF elements within this element's scope.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX
Child elements | ENTRY, ENTRYREF

Remarks

This element defines the number of times Windows Media Player repeats, or loops through, the clips defined by the ENTRY and ENTRYREF elements within this element's scope. Only the first REPEAT element in a metafile is valid; subsequent REPEAT elements are ignored.

If no COUNT attribute is defined, the content in the associated ENTRY and ENTRYREF elements repeats an infinite number of times. A value of zero causes Windows Media Player to ignore the REPEAT element and play the content once.

Example Code

<ASX VERSION="3.0">
   <ENTRY>
        <REF HREF="mms://example.microsoft.com/clip1.asf" />
<!-- This clip plays once. -->
   </ENTRY>

   <REPEAT COUNT="2">
      <ENTRY>
     <REF HREF="mms://example.microsoft.com/clip2.asf" />
     <REF HREF="mms://example.microsoft.com/clip3.asf" />
 <!-- These clips play twice. -->
      </ENTRY>
   </REPEAT>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


SKIN Element

The SKIN element specifies a URL to a border.

This element is supported only for Windows Media Player 7 or later.

Syntax

<SKIN
   HREF="URL"
/>

Attributes

HREF (required)

URL for a compressed border file with a file extension .wmz.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX
Child elements | None

Remarks

The SKIN element is used to create a border, which is similar to a skin but is displayed in the Now Playing area of the full mode Windows Media Player. The SKIN element is used only for borders, which appear inside the full mode Windows Media Player, and not for regular skins, which entirely replace the compact mode Windows Media Player.

The SKIN element is used by a Windows Media Download Package, a file with an extension .wmd, to enable a border to have content and to link to other sites. It is a compressed file that contains a compressed border file and a Windows Media metafile. A compressed border file, with an extension .wmz (Windows Media Zipped), includes a skin definition file with an extension .wms (Windows Media Skin).

A SKIN element has three components:

  • A skin
  • Some content
  • A metafile

Example Code

<ASX version = "3.0">
    <TITLE>A Skin Element</TITLE>
    <SKIN HREF = "YourTest.wmz" />

    <ENTRY>
        <PARAM name="YourAlbumTitle" value="YourTitle.jpg"/>
        <PARAM name="link" value="http://www.YourPath.com"/>
        <TITLE>(The Artist)-YourTitle</TITLE>
        <REF HREF="(The Artist)-YourSongTitle.wma"/>
    </ENTRY>

</ASX>

See Also

  • Borders for Windows Media Player
  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


STARTMARKER Element

The STARTMARKER element specifies a marker from which the Windows Media Player control will start rendering the stream.

Syntax

<STARTMARKER
   NUMBER="marker number"
   NAME="marker name"
/>

Attributes

NUMBER

The number of a numeric marker in the index. The default value is the beginning of the content if on-demand, or the current position in the stream if real-time.

NAME

The name of a named marker in the index. The default value is the beginning of the content if on-demand, or the current position in the stream if real-time.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ENTRY, REF
Child elements | None

Remarks

This element specifies the marker from which Windows Media Player is to start rendering the stream defined in the parent ENTRY or REF element.

Note Use this element with either the NUMBER or NAME attribute, but not both.

A STARTMARKER element defined within a REF element takes precedence over a STARTMARKER element defined within the REF element's parent ENTRY element. A STARTMARKER element also takes precedence over a STARTTIME element.

If the marker specified by a STARTMARKER element occurs later in the stream than the marker defined by an ENDMARKER element, no content plays, but no error is generated.

Example Code

<STARTMARKER NUMBER="14" />
<STARTMARKER NAME="Marker_StartHere" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


STARTTIME Element

The STARTTIME element defines a time index from which the Windows Media Player control will start rendering the stream.

Syntax

<STARTTIME
   VALUE="hh:mm:ss.fract"
/>

Attributes

VALUE (required)

The time index, in hours, minutes, seconds, and hundredths of seconds, from which Windows Media Player starts playing a stream defined in the associated element.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ENTRY, REF
Child elements | None

Remarks

This element defines a time index into the content where Windows Media Player is to start rendering the stream. This element can be used only with stored, on-demand content that has been indexed.

Example Code

<STARTTIME VALUE="1:30.0" />

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


TITLE Element

The TITLE elelment defines a text string specifying the title for an ASX or ENTRY element.

Syntax

<TITLE>
   text string
</TITLE>

Attributes

None.

Parent/Child Elements

Hierarchy | Elements
Parent elements | ASX, ENTRY
Child elements | None

Remarks

This element defines a text string that specifies the title of an ASX or ENTRY element. The title is displayed in the display panel and Properties dialog box.

When this element appears within an ASX element, the text is displayed as Show information. In Windows Media Player version 6.4, the text also appears on the Show tab of the Properties dialog box. When this element appears within an ENTRY element, the text is displayed as Clip information. In Windows Media Player version 6.4, the text also appears on the Clip tab of the Properties dialog box.

If a MOREINFO element is also used with the associated (parent) element, it is the title text that the user clicks to access the URL defined in the MOREINFO element.

Each parent ASX and ENTRY element should contain at most one child TITLE element. Multiple TITLE elements after the first will be ignored and will not be displayed.

Example Code

<ASX VERSION="3.0">
   <TITLE>Title of the Show</TITLE>
   <ENTRY>
      <TITLE>Title of the Clip</TITLE>
      <REF HREF="mms://example.microsoft.com/clip1.asf" />
   </ENTRY>
</ASX>

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Reference


File Name Extensions

There are specific guidelines for the use of file name extensions for Windows Media metafiles. Windows Media metafile extensions are used to identify the different types of Windows Media files. A file name extension provides an Independent Software Vendor (ISV) with information about the rendering requirements of an application that uses a particular extension, and enables content authors to target general types of media players.

The file name extension guidelines are listed in the following table. It is recommended that a file's MIME type, located in the file header, be used for file-type identification.

File name extension | MIME type | File content
.wma | audio/x-ms-wma | Windows Media file, with audio content only. Typically used to download and play files or to stream content.
.wmv | video/x-ms-wmv | Windows Media file with audio and/or video content. Typically used to download and play files or to stream content.
.asf | video/x-ms-asf | Legacy content. Typically used to download and play files or to stream content. May contain audio and/or video content. Typically used to download and play files or to stream content.
.wm | video/x-ms-wm | Reserved
.wax | audio/x-ms-wax | Metafiles that reference Windows Media files with the .asf, .wma or .wax file extensions.
.wvx | video/x-ms-wvx | Metafiles that reference Windows Media files with the .wma, .wmv, .wvx or .wax file extensions.
.asx | video/x-ms-asf | Metafiles that reference Windows Media files with the .wma, .wax, .wmv, .wvx, .asf, or .asx file extensions.
.wmx | video/x-ms-wvx | Reserved

Remarks

Scripting and digital rights management (DRM) must be supported by any application rendering Windows Media files.

See Also

  • Windows Media Metafile Elements Reference
  • Windows Media Metafile Guide
  • Windows Media Metafile Reference


Glossary

To find a term in the glossary, click the letter of the alphabet that is the first letter in the term you want to look up.

A | B | C | D | E | F | G | H | I | J | K | L | M
N | O | P | Q | R | S | T | U | V | W | X | Y | Z

A

.aiff

A Macintosh AIFF file. See also media formats.

.asf

A Windows Media file. Advanced streaming format. See also media formats.

.asx

A Windows Media file. Advanced stream redirector. See also media formats.

.au

A UNIX audio file. See also media formats.

.avi

A Windows multimedia video file. See also media formats.

ambient

In the context of Windows Media Player skin creation, an ambient attribute or event is one that applies to all or most of the skin elements documented in the SDK.

analog

Traditional format in which audio and video are transmitted using a wave or analog signal. May not work with digital speakers. Computers use digital signals.

anchor window

A small window that appears in the lower right corner of the screen when Windows Media Player is in compact mode. Right-click the anchor window to return to full mode. See also compact mode.

announcement

An announcement is a file that contains information about the URL for a media stream, including the multicast IP address, port, stream format, and other station settings. It is a metafile that can be generated automatically by Windows Media Services Administrator when a multicast station is created.

aspect ratio

The ratio of the width of an image to its height.

attribute

A piece of information in the form of a name-value pair that specifies a particular detail of an element in a markup language.

B

bandwidth

The data transfer capacity of a digital communications system, such as the Internet or a local area network (LAN). Bandwidth is usually expressed in the number of bits that a system is capable of transferring in a second: bits per second (bps). High bandwidth or broadband refers to a network capable of a fast data transfer rate.

bit rate

The speed at which digital audio and video content streams from a source, such as a file, to be rendered properly by a player, or the speed at which binary content in general is streamed on a network. Bit rate is usually measured in kilobits per second (Kbps), for example, 28.8 Kbps. The bit rate of a Windows Media file or live stream is determined during the encoding process, when the streaming content is created. Bandwidth is the total bit-rate capacity of a network. For audio and video content to render properly when streaming over a network, the bandwidth of the network must be high enough to accommodate the bit rates of all the different content that is being streamed concurrently.

broadcast

Describes how a client experiences receiving a stream. A broadcast stream can be unicast or multicast. In a broadcast connection, the client is passive and does not control when the stream starts or stops. In an on-demand connection, the client is active and controls when the stream is started and stopped.

broadcast multicast

Delivery of one stream by a Windows Media server to many clients. From a client perspective, a broadcast is a connectionless experience because the client never connects to a Windows Media server.

broadcast unicast

A point-to-point connection that a client initiates to a publishing point in a Windows Media server.

buffer

A small amount of RAM that Windows Media Player uses as a loading area for information before playing it. When you play a file or stream, Windows Media Player fills up the buffer before it begins playing so that you won't notice minor problems with traffic on the Internet or the local network.

C

caption

Text that accompanies an image or video stream, either as a supplemental description or a transcript of spoken words.

CD

See compact disc .

client

Typically, the software that makes requests in client/server communications. Client software requests connections and communications with servers. On a local area network or the Internet, a computer that accesses shared network resources provided by another computer (called a server). A computer playing content with Windows Media Player is often called the client.

clipping image

An image that is not displayed, but instead defines the visible region of another image.

codec

Short for compressor/decompressor. Codecs are various types of computer algorithms that are applied to audio, video, and image files to compress the size of the files. The benefit of this is that the files do not use as much disk space when stored or network bandwidth when streamed. To open a compressed file, the same codec must be used to decompress the file. If your computer does not have the correct codec to decompress a file, Windows Media Player will attempt to download the codec for you.

compact mode

Windows Media Player can appear in two modes: full mode or compact mode. Compact mode is the smaller, reduced-functionality mode that is customizable. It allows more room on your screen for using other applications. To make sure you are in compact mode, press CTRL+2.

compact disc (CD)

A small disc containing digital information that is stored or retrieved optically through the use of lasers.

compression

The coding of data to reduce file size or the bit rate of a stream. Content that has been compressed is decompressed for playback.

content

Data that servers stream to a client or clients. Content can originate from live audio or live video presentation, stored audio or video files, still images, or slide shows. The content must be translated from its original state into a Windows Media format before a Windows Media server can stream it. Windows Media servers can stream live streams or stored Window Media files as content.

D

down image

An image that is displayed when the mouse button is in the down position over a control.

download

A method of delivering content over a network in which the content is copied to a client computer and then played locally. This method is different from streaming, because in streaming, the source data is not copied to the client computer. See also streaming.

E

element

A unit of information within a markup language that is defined by a tag, or a pair of tags surrounding some content, and includes any attributes defined within the initial tag.

encode

To convert information into a specified digital format for convenient storage and retrieval using computer technology, usually involving compression technology and encryption technology.

error correction

A method of controlling and correcting data transmission errors that occur when streaming.

event

An action that occurs in response to a particular condition within a program, such as a key press or mouse click.

event handler

A method within a program that is called automatically whenever a particular event occurs.

extension

Usually three letters, sometimes more, that are added to the end of a file name. The extension is distinguished from the rest of the file name by a period. The file extension, such as .avi or .txt, usually indicates the file type and the program used to play or open the file. Also known as file extension or file name extension.

F

file format

The structure of a file. See also file type; extension;media formats.

file type

Usually indicated by the file name extension. The file type determines which program can be used to play or open a file.

full mode

Windows Media Player can appear in two modes: full mode or compact mode. Full mode is the fully functional mode with complete sets of toolbars. To make sure you are in full mode, press CTRL+1.

G

genre

A category for grouping music, such as "classical" or "jazz".

global attribute

An attribute used within a skin definition file that is accessible from anywhere, rather than being associated with a particular element.

H

hover image

An image that is displayed for a control whenever the mouse pointer hovers over it.

HTTP

Hypertext transfer protocol.

L

licensed file

A Windows Media file that has an associated license restricting the playing of that file. The restrictions stated in the license will vary depending on the license creator. Any file created by copying a CD track using Windows Media Player is assigned a license that restricts the playing of that file to the computer where the file was created.

lossy

An image compression technique that decreases image quality in order to reduce the file size.

M

.mid

A Musical Instrument Digital Interface (MIDI) file. See also media formats; MIDI

.midi

A Musical Instrument Digital Interface (MIDI) file. See also media formats; MIDI.

.mp2

An MPEG video file. See also media formats; Moving Picture Experts Group.

.mp3

An MPEG video file. See also media formats; Moving Picture Experts Group.

.mpg

An MPEG video file. See also media formats; Moving Picture Experts Group.

.mpg2

An MPEG video file. See also media formats; Moving Picture Experts Group.

mapping image

An image that is not displayed, but instead defines significant regions on another image through the use of colors. A mapping image allows arbitrarily complex shapes to be defined easily, without the specification of long lists of coordinates.

media formats

Types of media files. Formats supported by Windows Media Player include the following: .aif, .aifc, .aiff, .asf, .asx, au, .avi, .cda, .ivf, .m1v, .m3u, .mid, .midi, mp2, .mp3, .mpa, .mpe, .mpeg, .mpg, .mpv2, .rmi, .snd, .wax, .wav, .wma, .wms, .wmv, .wvx, .wmz.

metadata

Information about data. For Windows Media Technologies, metadata, such as content title, author, copyright, and description, can be included in a Windows Media file and in a metafile script.

metafile

In Windows Media Technologies, a file that provides information about Windows Media files and their presentation. There are several types of metafiles designated by the following extensions: .asd, .asx, .wax, .wvx, .wmx and .nsc.

metafile playlist

A Window Media metafile that provides information that Windows Media Player uses to receive unicast streams, multicast streams, and other supported media from an intranet or the Internet.

method

A programming function that is related to a particular object and can be called to modify the object's properties or to achieve a particular effect that the object is responsible for. Methods can be passed pieces of information called parameters in order to modify the resulting behavior. Frequently, the result of a method call is the return of a different piece of information that can then be used by another part of the program.

Microsoft Media Server (MMS) protocol

A protocol specific to Windows Media Technologies that is used by clients to reference and stream Windows Media content from a unicast publishing point on a Windows Media server. Windows Media Player opens a Windows Media file using a URL, such as mms://Server/File.asf.

MIDI

See Musical Instrument Digital Interface.

MIME

Multipurpose Internet Mail Extension. It is a multimedia file format that is a standard for multi-part multimedia electronic mail messages and World-Wide Web hypertext documents on the Internet. MIME provides the ability to transfer non-textual data, such as graphics, audio and fax.

Moving Picture Experts Group (MPEG)

There are two major MPEG standards: MPEG-1 and MPEG-2. The most common implementations of the MPEG-1 standard provide a video resolution of 352-by-240 at 30 frames per second (fps). This produces video quality slightly below the quality of conventional VCR videos.

A newer standard, MPEG-2, offers resolutions of 720x480 and 1280x720 at 60 fps, with full CD-quality audio. This is sufficient for all the major TV standards, including NTSC and even HDTV.

MP3

MPEG Audio Layer 3. An audio compression technology that is part of the MPEG-1 and MPEG-2 specifications. Developed in Germany in 1991 by the Fraunhofer Institute, MP3 uses perceptual audio coding to compress CD-quality sound by a factor of 12, while providing almost the same fidelity.

.mpeg

A Moving Picture Experts Group video file. See also media formats; Moving Picture Experts Group.

MPEG-1

See Moving Picture Experts Group.

MPEG-2

See Moving Picture Experts Group.

multicast

A one-to-many client/server connection in which multiple clients receive the same stream from a server. To receive a multicast, a client listens to a specific IP address on a multicast-enabled network, like tuning a television to a specific channel. In contrast, a unicast is a one-to-one connection in which each client receives a separate stream from a server.

Musical Instrument Digital Interface (MIDI)

A standard protocol for the interchange of musical information between musical instruments, synthesizers and computers. It defines the codes for a musical event, which include the start of a note, its pitch, length, volume, and musical attributes, such as vibrato. It also defines codes for various button, dial, and pedal adjustments used on synthesizers.

O

object

A collection of properties and methods that serve a particular purpose and are treated as a unit.

P

packet

A small unit of information transmitted over a network.

parameter

A piece of information that is passed into a method in order to achieve a particular result.

playlist

A personalized list of links to various audio and video files on your computer, your network, or the Internet, including radio stations and broadband broadcasts. You can create a playlist from any combination of media sources. The items in the list are played sequentially. You can change the order of items in your playlist by dragging and dropping.

port

A number that enables IP packets to be sent to a particular process on a computer connected to a network. Ports are most often identified with a particular service. For example, port 80 on an Internet computer indicates a Web server. Windows Media server components, when in use, bind to particular ports. By default, the Windows Media Unicast service binds to port 1755 and the Windows Media Station service binds to port 7007. If HTTP streaming is enabled for a service, then that service switches to use port 80.

preset

A predefined setting. For Windows Media Player, there are presets defined for both equalizer settings and for most visualizations.

proxy server

A computer and associated software that will pass on a request for a URL from a browser to an outside server and return the results. This can provide clients that are sealed off from the Internet a trusted agent that can access the Internet on their behalf, or provide a cache of items available on other servers that are presumably slower or more expensive to access.

progress bar

A meter-like indicator within a graphical user interface that illustrates the progress of a gradual process, such as a file download.

property

A piece of information that specifies a particular detail of an object.

protocols

Standard formats and processes for transmitting information over a network. Available protocols for use with streaming media are Multicast, UDP, TCP, and HTTP.

publishing point

A virtual directory used for storing content that is available to clients, or for accessing a live stream. Clients reach a publishing point through its URL.

S

.smi

A Synchronized Accessible Media Interchange (SAMI) file. See also Synchronized Accessible Media Interchange (SAMI).

.snd

A UNIX file. See also media formats.

SAMI

See Synchronized Accessible Media Interchange (SAMI) File.

skin

A file that customizes the look and functionality of Windows Media Player. When Windows Media Player is in compact mode, it will appear and work as the skin directs.

skin definition file

A text document in XML format that specifies the elements present within a skin, along with their relationships and additional functionality. A skin definition file has a .wms file extension.

slider

A control within a graphical user interface in which an indicator called a thumb can be moved along a continuous path into a number of different positions.

sticky

A characteristic of a button control within a graphical user interface in which the button, when clicked, remains in a down position until it is clicked again. A sticky button is also known as a toggle.

stream

Data transmitted across a network and any properties associated with the data. Streaming is the general term used to describe the method used by Windows Media Services to transmit data to client computers. Specifically, streams can be transmitted as either unicast streams or multicast streams. Streaming data allows the player to begin rendering the data immediately instead of waiting for the entire file to be downloaded.

streaming

A method of delivering content, in which media is located on a server and then played by sending the data across a network in a continuous flow. Streamed media is differentiated from downloaded media because the media is sent in a steady stream to the computer but is not stored on the computer.

Synchronized Accessible Media Interchange (SAMI) File

A file containing text strings associated with specified times within a media presentation. The text strings appear in the Windows Media Player closed captioning display area as the presentation reaches the designated times. SAMI files can also include conditional text strings for providing closed captioning in different languages.

T

tag

A portion of an XML file designated by a pair of angle brackets and the information between them that identifies an element and any of its attributes.

thumb

The part of a slider control that can be moved to set the slider position.

ToolTip

A small text box usually containing help information that pops up when a mouse pointer hovers over a control.

tracks

Individual songs from a CD.

U

Unicode

A universal character encoding standard. A set of uniquely encoded characters of all scripts used by living languages. A text encoded in Unicode consists of a stream of 16-bit Unicode characters without any embedded controls.

UNIX

An interactive, time-sharing operating system. UNIX was the first source-portable operating system and is now offered by many manufacturers.

URL

A Uniform Resource Locator, identifying a protocol, host computer, directory, and file name for the purposes of accessing that file from another computer on a network.

V

video settings

Settings that allow the modification of video brightness, contrast, hue, and saturation.

visualization

Splashes of color and geometric shapes that change with the beat of the audio that is currently playing.

visualization collection

A group of visualizations centered on specific themes.

W

.wav

A Windows audio file. See also media formats.

.wax

A Windows Media audio redirector file. A special type of metafile playlist for use with Windows Media files with a .wma extension. The .wax extension file includes information about the location of the .wma file on the Windows Media server and the properties of the file. It is similar to the playlist files with an .asx extension and their interaction with media files with an .asf extension.

See also media formats.

.wma

A Windows Media audio file. A special type of advanced streaming format file for use with audio content encoded with the Windows Media Audio codec. The .wma extension indicates a file format and how the content is encoded.

See also media formats.

.wms

A Windows Media Player skin definition file. A skin definition file is an XML text document that defines the elements present within a skin along with their relationships and functionality. See also media formats.

.wmv

A Windows Media video file. See also media formats.

.wmz

A Windows Media Player skin file that combines a skin definition file and its supporting graphic files into one file using zip compression technology. See also media formats.

.wvx

A Windows Media redirector file. See also media formats.

Windows Media client

The ActiveX control, called the Windows Media Player control, that receives and renders content from Windows Media server components. The client can be on the same computer as the server, or it can be on another computer.

Windows Media file

A file, typically with a .wma, or .wmv, or .asf extension, which contains audio, video, or script data. These files are highly optimized for streaming, yet they provide dynamic sound when downloaded and played by Windows Media Player.

Windows Media format

The format used by Microsoft Windows Media Technologies (or a third party product that incorporates a licensed Windows Media technology) to author, store, edit, distribute, stream, or play timeline-based content.

Windows Media Station (.nsc) file

Contains information that Windows Media Player uses to connect to and play a multicast stream, such as the multicast IP address, port, stream format, and other station settings. Unlike a unicast stream, no header information is contained in a multicast stream. That information comes from an .nsc file. Windows Media Player usually opens an announcement (.asx, .wax, or .wvx) file first, that points it to the location of the .nsc file.

X

XML

Extensible Markup Language. A simple dialect of SGML suitable for use on the World-Wide Web and for the creation of custom markup languages such as the Windows Media Player skin definition language.

Previous


Legal Notice

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2000-2001 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows Media, Windows NT, ActiveSync, ActiveX, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, FrontPage, JScript, Microsoft Press, MSN, NetShow, Outlook, PowerPoint, SQL Server, Visual Basic, Visual C++, Visual InterDev, Visual J++, Visual Studio, WebTV, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

This software is based in part on the work of the Independent JPEG Group.

GIF decompression code, copyright 1990, David Koblas. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.