Scheduling Media Clips

You can schedule media clips to play before, during, and after a Smooth Streaming media presentation. This topic shows an example of how to insert advertising clips during programming.

Scheduling Clips by Marker

One way to insert a clip into Smooth Streaming programming is to call the ScheduleClip method from a handler for the MarkerReached event. (This scenario depends on functionality that was implemented in the example code in Timeline Markers and Events.)

Adding Clip Information

To schedule a clip, initialize a ClipInformation object that specifies the media clip to play by setting its ClipUri and Duration property values, as shown in the following example:

// List for advertising clips.
List<ClipInformation> clips = new List<ClipInformation>(5);

private void InsertClipCheckbox_Checked(object sender, RoutedEventArgs e)
{
    clips.Add(new ClipInformation(true,
    new Uri("https://serverName/clip.ism/Manifest"),
    new Uri("https://msdn.microsoft.com/en-us/library/microsoft.web.media.smoothstreaming.aspx"),
    new TimeSpan(1789250001)));
}

In this example, when the media stream hits the marker that is 1,789,250,000 ticks from the beginning of the stream, the clip identified by the ClipInformation object at clips[0] will interrupt the currently playing stream, play the clip to the end of its duration, and then resume the media stream that was interrupted.

Scheduling the Clip by the Marker-Reached Event

To handle the MarkerReached event, assign a delegate for it as shown in the following code:

SmoothPlayer.MarkerReached += 
      new TimelineMarkerRoutedEventHandler(SmoothPlayer_MarkerReached);

In the MarkerReached handler, identify the marker that will trigger the insertion of the media clip. The following example selects a marker if the System.Windows.Media.TimelineMarker.Text member of the System.Windows.Media.TimelineMarkerRoutedEventArgs object that is passed to the event handler equals "Chapter 3" and if a UI element named InsertClipCheckbox is selected. The code uses the ScheduleClip(ClipInformation, Boolean, Object) method to insert the clip. The method takes parameters that specify a ClipInformation instance, a Boolean value that indicates whether to pause when the clip is finished playing, and the SmoothStreamingMediaElement object that will play the clip.

void SmoothPlayer_MarkerReached(object sender, TimelineMarkerRoutedEventArgs e)
{

    if (e.Marker.Text.Contains("Chapter 3") && InsertClipCheckbox.IsChecked.Value == true)
    {
        SmoothPlayer.ScheduleClip(clips[0], true, SmoothPlayer);
    }
}

Passing Information Using the userData Parameter

The third parameter of the ScheduleClip(ClipInformation, ClipContext, Object) method is the userData parameter. The value of the parameter is saved as a member of the ClipContext instance that is created by the ScheduleClip(ClipInformation, ClipContext, Object) method. The application can use this parameter to pass anything it requires; typically, the parameter is used to pass something that can identify the ClipContext type. In the following example, SmoothPlayer is passed as the value of userData. Code that appears later in this document shows how to cast the userData value to type SmoothStreamingMediaElement in order to retrieve the Smooth Streaming client (player) that generated the ClipContext instance.

SmoothPlayer.ScheduleClip(clips[0], new TimeSpan(0), true, SmoothPlayer);

If the application must pass more information than is shown in this example, it can create a class to contain all the data and then pass that type as the userData value.

Specifying the Click-Through Action for a Clip

If the user clicks the SmoothStreamingMediaElement surface while the inserted clip is playing, the method that handles the event can access the object assigned to the Context property from the ClipEventArgs instance that is passed to the method. The ClipInformation property contains the ClickThroughUri value that was assigned when the ClipInformation object was initialized.

To handle the ClipClickThrough event, assign a delegate as shown in the following example:

  SmoothPlayer.ClipClickThrough +=
       new EventHandler<ClipEventArgs>(SmoothPlayer_ClipClickThrough);

The following implementation of ClipClickThrough shows how to open a new browser window in order to navigate to the target specified in the ClickThroughUri property.

void SmoothPlayer_ClipClickThrough(object sender, ClipEventArgs e)
{
    System.Windows.Browser.HtmlPage.Window.Navigate(e.Context.ClipInformation.ClickThroughUri, "_newWindow");
}

The marker-reached event is one method of scheduling clips. Other applications might use sparse tracks or polling for live ad insertions. For more information, see Manifest Merge.

Note

Smooth Streaming clips scheduled by using ScheduleClip methods require manifests that start at the zero time stamp.

Scheduling a Pre-Roll Scenario

The pre-roll scenario schedules a clip or clips to run immediately before the main video starts. The ManifestReady event provides an opportunity to schedule clips to precede the main presentation.

To use the pre-roll scenario, handle the ManifestReady event. The following event handler shows how to initialize the pre-roll clip. The ScheduleClip method is an overloaded method. The pre-roll scenario uses the ScheduleClip(ClipInformation, TimeSpan, Boolean, Object) method overload that contains the StartTime parameter. Setting the StartTime parameter to zero schedules the clip to play at the beginning of the Smooth Streaming presentation. As in the previous example, the pauseTimeline parameter is set to true so the viewer does not miss the segment of the playback that would otherwise run in the background while the scheduled clip plays. (Setting the pauseTimeline parameter to false is useful for live streaming.)

The following example shows how to schedule a pre-roll scenario.

void SmoothPlayer_ManifestReady(object sender, EventArgs e)
{
    if (!PremiumAccount)
    {
        if (InsertClipCheckbox.IsChecked == true)
        {     
            SmoothPlayer.ScheduleClip(clips[0], new TimeSpan(0), true, SmoothPlayer );
            SmoothPlayer.Play();
        }
    }
}

Chaining Clips

You can schedule clips to run in a series, or chain them. This scenario uses the ScheduleClip(ClipInformation, ClipContext, Object) method overload that has the clipToAppendTo parameter, which is of type ClipContext. To chain clips, assign the ClipContext instance of a running clip to the clipToAppendTo parameter of the clip that will follow it in the series.

The following example uses the ClipProgressUpdate event handler to schedule a clip to follow the clip that is reporting its progress in this event. In this case, the event will schedule successive clips up to the count of clips in the clips collection.

void SmoothPlayer_ClipProgressUpdate(object sender, ClipPlaybackEventArgs e)
{
    if (clipIndex < (clips.Count - 1) && e.Progress == ClipProgress.ThirdQuartile)
    {
        SmoothPlayer.ScheduleClip(clips[++clipIndex], e.Context, SmoothPlayer);
    }
}

See Also

Concepts

Events

Timeline Markers and Events

Manifest Merge