ASP.NET MediaPlayer Server Control

Introduction

The ASP.NET MediaPlayer server control, available in the System.Web.UI.SilverlightControls namespace, enables you to integrate media sources such as audio (WMA) and video (WMV) into a Web application, without requiring any knowledge of XAML or JavaScript.

The MediaPlayer control generates the appropriate markup and code to display and control media in the media player UI. The MediaPlayer control can use pre-built skins, or you can create custom skins. For example, you can reference a custom XAML document that is generated through Microsoft Expression Encoder and that supports captions, chapters, and markers in the media source. When you configure the MediaPlayer control to reference a pre-built skin, the associated XAML document is copied into the project. The MediaSkinSource property of the MediaPlayer is also set to point to the referenced skin.

In addition, you can also work with a client JavaScript object that manages user interaction with the player.

Note

Web pages that use the MediaPlayer server control must include a ScriptManager control.

This topic discusses the following aspects of working with the MediaPlayer control:

  • Defining MediaPlayer control chapters with the Chapters property and by using a media definition file.

  • Choosing a media skin for the MediaPlayer control.

  • Customizing a MediaPlayer control skin.

  • Configuring the MediaPlayer control to automatically load and play.

  • Using client script to manage the MediaPlayer control.

  • Defining MediaPlayer control markers and captions.

  • Creating client playlists.

To be able to work with the MediaPlayer control, you need:

  • The Silverlight 2 SDK Beta 2.

  • The .NET Framework version 3.5.

MediaPlayer Server Control Syntax

The MediaPlayer server control inherits from the Silverlight server control.

Using the MediaPlayer Server Control

To use the MediaPlayer server control, you reference a media source file (for example, a .wmv, .wma, or .mp3 file) and select a built-in skin.

The following example shows the declarative markup for a MediaPlayer server control that is configured to play the file Professional.xaml and with various properties set. 

<asp:MediaPlayer 
    ID="MediaPlayer1" 
    runat="server" 
    MediaSource="~/Media/video.wmv"
    MediaSkinSource="~/MediaSkins/Professional.xaml"
    ScaleMode="Stretch"
    AutoLoad="true"
    AutoPlay="false"
    PluginBackground="Black"
    Height="240px" 
    Width="320px">
</asp:MediaPlayer>

The MediaPlayer control creates the Sys.UI.Silverlight.MediaPlayer client script class (based on the model used in the ASP.NET AJAX Extensions) that provides a JavaScript programming model to control the client player.

The MediaPlayer control supports a variety of media file types that include .wmv, .wma and .mp3, and can be used to point to content available through the mms://<url moniker> protocol or to reference client playlists as .asx files.

Language:
View

Run an example of this feature.

Creating and Using Chapters in the MediaPlayer Control

You can define chapters in a video media source by using the Chapters collection property. Typically the chapters also represent markers in the video. If you encode a video source by using the Microsoft Expression Media Encoder tool, you can define markers in the media and provide thumbnail images for the markers. The generated output from the tool creates the encoded video and the thumbnail image files that you can reference from the MediaPlayer control.

You can use Visual Studio to create the MediaPlayer control and use Web forms designer in Visual Studio to select chapter images. Additionally, you can create the Chapters element with MediaChapter controls in the markup.

The following example shows the declarative markup for a MediaPlayer control with the Chapters property set to define three chapters.

<asp:MediaPlayer 
    ID="MediaPlayer1" 
    runat="server" 
    MediaSource="~/Media/video.wmv"
    MediaSkinSource="~/MediaSkins/Professional.xaml"
    PlaceholderSource="~/media/image0.jpg"
    ScaleMode="Stretch"
    AutoLoad="true"
    AutoPlay="false"
    PluginBackground="Black"
    Height="240px" 
    Width="320px">
    <Chapters>
        <asp:MediaChapter 
            Position="5" 
            ThumbnailSource="~/Media/image1.jpg"
            Title="Section 1." />
        <asp:MediaChapter 
            Position="10" 
            ThumbnailSource="~/Media/image2.jpg"
            Title="Section 2." />
        <asp:MediaChapter 
            Position="15" 
            ThumbnailSource="~/Media/image3.jpg"
            Title="Section 3." />
    </Chapters>
    <PluginNotInstalledTemplate>
        Silverlight is not installed.    
    </PluginNotInstalledTemplate>    
</asp:MediaPlayer>

In the previous example, the MediaPlayer control is set to use the Professional.xaml media skin. This XAML media-skin file provides support for chapter information, and when users hold the mouse just underneath the video area, a scrollable chapter list is displayed. Selecting a chapter from the list moves the position in the media to the selected chapter in the video.

Language:
View

Run an example of this feature.

The Sys.UI.Silverlight.MediaPlayer object raises the Sys.UI.Silverlight.MediaPlayer.chapterStarted event when a chapter starts, and it raises the Sys.UI.Silverlight.MediaPlayer.markerReached event when a marker is reached. You can call the get_chapters function to query the Sys.UI.Silverlight.MediaPlayer.chapters property collection. You can call the get_currentChapter function to query the Sys.UI.Silverlight.MediaPlayer.currentChapter property.

For information about how to work with chapters and markers in client script, see Defining MediaPlayer Control Markers and Captions in this topic.

Adding a Media Definition File

You can define the media information for the MediaPlayer control by setting the control's Chapters property. Alternatively, you can define media information in a media definition file. The media definition file is an XML document that includes information that the MediaPlayer control can read to obtain media details, such as a media source location and chapter information. To reference a media definition file in the MediaPlayer control, you set its MediaDefinition property.

The following example shows the contents of a media definition file.

<mediaDefinition>
  <mediaItems>
  <mediaItem mediaSource="video.wmv" 
       placeholderSource="image0.jpg">
    <chapters>
      <chapter position="5.00" 
          thumbnailSource="image1.jpg"
          title="marker1" />
      <chapter position="10.00" 
          thumbnailSource="image2.jpg"
          title="marker2" />
    </chapters>
    </mediaItem>
  </mediaItems>
</mediaDefinition>

References in the media definition file are relative to the file. For example, if the media definition file includes a mediaItem element that has a mediaSource attribute that does not include a path, the file referenced by the mediaSource attribute must be in the same directory as the media definition file.

A MediaPlayer control can include both a Chapters collection and a reference to media definition file. If so, the media definition file takes precedence if it contains any one of the following:

  • A Chapters element.

  • A placeholderSource property.

  • A mediaSource property.

The Expression Media Encoder can generate a media definition file.

Choosing a Media Skin for the MediaPlayer

The MediaPlayer control plays media in a border area. This border area is called the media skin (media player UI). It contains the controls, such as buttons and sliders, that users click to view the file, stop and start it, and so on. The MediaPlayer control references a XAML (.xaml) file that contains the media skin details.

The MediaPlayer control has multiple skin files. Media skins are in separate .xaml files to enable easy modification of the XAML content. You can copy, modify and create new media skins.

The provided media skin files are as follows:

  • Professional.xaml

  • AudioGray.xaml

  • Basic.xaml

  • Classic.xaml

  • Expression.xaml

  • Futuristic.xaml

  • Console.xaml

  • Simple.xaml

The default media skin, that is contained as part of the MediaPlayer, is the same skin as the media skin that is contained in Classic.xaml.

In Visual Studio, when you import a media skin, the XAML file is copied to your project. The MediaSkinSource property of the MediaPlayer control is set to the URL of the media skin file.

At design time, the MediaPlayer control is rendered by using the XAML of the media skin with appropriate scaling behavior. When the MediaSkinSource property of the MediaPlayer control is changed, the design-time rendering is updated based on the new XAML.

Customizing a MediaPlayer Control Skin

To change the appearance of the MediaPlayer control's rendered skin, you can use a XAML editor and modify the .xaml file. For example, you might create a custom skin that incorporates a storyboard, a color scheme, or new functionality.

Note

You can use Microsoft Expression Blend or another tool to create or modify the XAML.

The following example shows a MediaPlayer control with a skin that is based on an exported version of the Professional skin.

Language:
View

Run an example of this feature.

The XAML markup for a skin uses specifically named elements referenced by the JavaScript Sys.UI.Silverlight.MediaPlayer client class, or classes that derive from it.

When you use a .xaml file that has the MediaPlayer control, you can also create a custom JavaScript client class to interact with the XAML code in order to provide custom interaction and handling. The MediaPlayer control enables you to associate a new client type to associate with a custom or pre-built skin. To include the JavaScript library that contains the definition of your custom type, you add it to the ScriptManagercontrol. The following example shows the markup for a ScriptManagercontrol and a MediaPlayer control that uses a custom JavaScript class. In the example, the Custom.js file is assumed to contain the definition for the Custom.MediaPlayer class.

<asp:ScriptManager runat="server" ID="ScriptManager1"
  <Scripts> 
    <asp:ScriptReference Name="SilverlightPlugin.js"/> 
    <asp:ScriptReference Name="SilverlightControl.js"/> 
    <asp:ScriptReference Path="Custom.js"/> 
  </Scripts> 
</asp:ScriptManager > 

<asp:MediaPlayer runat="server" 
    ID="MediaPlayer1" ScaleMode="Stretch" AutoPlay="true" 
    MediaSource="~/media/expressionstudio.wmv" 
    Height="240" Width="320" PluginBackground="blue" 
    Source="Custom.xaml" ScriptType="Custom.MediaPlayer" >
 </asp:MediaPlayer>

Automatically Loading and Playing the MediaPlayer Media File

The AutoLoad property of the MediaPlayer control specifies whether the media source is loaded immediately after the MediaPlayer control is loaded. The autoPlay property specifies whether the media file plays as soon as it is loaded.

The MediaPlayer control is loaded when the value of the mediaSource property is set on the client. The AutoLoad and autoPlay properties are useful when a page contains multiple MediaPlayer controls and you want only one media file to load and play automatically.

If AutoLoad and autoPlay are both set to false, the Start button is displayed in the MediaPlayer control. Clicking the start button downloads and plays the media file. If the media is already loaded (for example, if AutoLoad is set to true and autoPlay is set to false), the Start button is not displayed and the Play button is enabled.

Using Client Script with the MediaPlayer Control

The MediaPlayer control provides an instance of the Sys.UI.Silverlight.MediaPlayer JavaScript class. This JavaScript class is used to handle the interaction with the XAML and the media on the client by exposing properties, methods, and events. This class enables you to interact with the player by using JavaScript. (The class follows the ASP.NET AJAX Extensions pattern and therefore has a dependency on the ASP.NET AJAX Extensions framework.) This class is automatically created and is attached to the DOM element that is rendered for the plug-in at run time. The JavaScript class is responsible for handling actions on the player for specific Silverlight objects. For example, if the document contains a canvas named “PlayPauseButton”, this canvas is wired up to the play and pause JavaScript methods.

You can bind client-script functions to client events in the MediaPlayer control by setting the client properties in declarative markup instead of by writing JavaScript code. Many of the events take parameters that include context information for that event. The following example shows the markup for the MediaPlayer control that binds the client OnClientChapterStarted property to the client Sys.UI.Silverlight.MediaPlayer.chapterStarted event.

<asp:MediaPlayer runat="server" ID="MediaPlayer1" 
    ScaleMode="Stretch" AutoPlay="true" 
    MediaSource="expressionstudio.wmv" 
    Height="240" Width="320" 
    PluginBackground="blue" 
    MediaSkin="Professional" 
    onClientChapterStarted="chapterStarted">
   <Chapters> 
    <asp:MediaChapter 
        ThumbnailSource="MarkerThumb 00.00.00.jpg" Position="0.0" 
        Title="Chapter 1" /> 
    <asp:MediaChapter 
        ThumbnailSource="MarkerThumb 00.00.10.jpg" Position="10" 
        Title="Chapter 2" /> 
    <asp:MediaChapter 
        ThumbnailSource="MarkerThumb 00.00.24.jpg" Position="24" 
        Title="Chapter 3" /> 
  </Chapters> 
</asp:MediaPlayer>

The following is an example of a method that is called when the Sys.UI.Silverlight.MediaPlayer.chapterStarted event is raised.

<script type="text/JavaScript">
    function chapterStarted(sender, chapterEventArgs) {
        var chapter = sender.get_currentChapter();
        $get('Chapters').innerHTML = "Chapter Info: " + chapter._title;
    }
</script>

By using the client Sys.UI.Silverlight.MediaPlayer instance, you can get information about the player and the media file that it is playing. Any interaction with the Sys.UI.Silverlight.MediaPlayer object should occur after the plug-in has finished loading the XAML file that it references, and after the media file has been loaded. For example, to obtain the markers for a media file, the file must have finished loading. The Sys.UI.Silverlight.MediaPlayer instance provides events such as Sys.UI.Silverlight.MediaPlayer.mediaOpened, Sys.UI.Silverlight.MediaPlayer.mediaFailed, and Sys.UI.Silverlight.MediaPlayer.mediaEnded that are raised to indicate the state of the media file.

The following example shows a series of chapters. As each chapter is reached, the chapter title is displayed.

Language:
View

Run an example of this feature.

Defining MediaPlayer Control Markers and Captions

You can define a list of chapters that are related to your media source through the MediaPlayer control. If you use the Microsoft Expression Media Encoder tool, you can define markers in the media and provide a placeholder image for the markers when you encode the video. You can then use the markers to define chapters in the MediaPlayer control.

Similarly, you can create other markers and special markers that are referred to as script commands. These let you define an arbitrary string for the marker that defines its type and another string for its value. By using the instance of the Sys.UI.Silverlight.MediaPlayer class that is created by the MediaPlayer control, you can handle the markerReached event. In the handler for this event, you might pause the media file and execute new XAML storyboards, insert new elements or ads, or perform other tasks.

The following example shows how to manipulate the marker and chapter information. It also shows interaction with the JavaScriptSys.UI.Silverlight.MediaPlayer instance. This example shows how to use a script command that defines a custom type named ad. The marker data defines another video (an ad) to play by using dynamically inserted XAML markup.

Language:
View

Run an example of this feature.

Creating Client Playlists

The MediaPlayer server control supports the media formats supported by Silverlight. For more information, see Supported Media Formats and Protocols in Silverlight on the MSDN Web site. You can define a client playlist that is in the form of an Advanced Stream Redirector file (.asx file) for the MediaPlayer server control. An .asx file is in an XML format that defines the playlist of media entries. Internal URLs are defined relative to the page that the .asx file is loaded from. You can modify the file to prevent skipping, show for specific durations or sections of videos, and other capabilities. The following example shows the definition of the MediaPlayer server control that references an .asx file

<asp:MediaPlayer runat="server" ID="MediaPlayer1" 
  ScaleMode="Stretch" 
  AutoPlay="true" 
  MediaSource="playlist.asx" 
  Height="240" Width="320" 
  PluginBackground="blue"/>

The following example shows the contents of the .asx file. Note that not all elements and features of an .asx file are supported by Silverlight. For more information, see the Silverlight Web site.

<ASX version="3.0">
 <TITLE>Client Playlist</TITLE>
  <ENTRY>
    <TITLE>Movie One</TITLE>
    <AUTHOR>Contoso</AUTHOR>
    <COPYRIGHT>(c) 2008 Contoso</COPYRIGHT>
    <STARTTIME VALUE="00:00:00.00"/>
    <DURATION VALUE="00:00:10.00"/>
    <REF HREF="movie_one.wmv"/>
  </ENTRY>
  <CLIENTSKIP="NO">
    <TITLE>Movie Two</TITLE>
    <AUTHOR>Contoso</AUTHOR>
    <COPYRIGHT>(c) 2008 Contoso</COPYRIGHT>
    <STARTTIME VALUE="00:00:20.00"/>
    <DURATION VALUE="00:00:10.00"/>
    <REF HREF="movie_two.wmv" />
  </ENTRY>
</ASX>

The following example shows how to use an .asx file to define a client playlist. In this example, a movie in the list is defined as "not skippable", which causes some of the player controls to be disabled.

Language:
View

Run an example of this feature.

See Also

This topic is ASP.NET Extensions documentation and is unsupported by Microsoft. Blank topics are included as placeholders and existing content is subject to change in future releases.