How to: Integrate with the Music and Videos Hub for Windows Phone

The Music + Videos Hub is divided into four distinct lists:

• Zune is the launch point for music, videos, podcasts, radio, and Zune Marketplace. The Play button next to music plays the entire music collection in shuffle mode.

• History contains recently played music, videos, playlists, artists, podcasts, FM radio stations, and content from third-party providers. Update this list when your Music + Videos Hub application plays media.

• New contains an updated list of new music, videos, or podcasts synced to the phone or downloaded from Zune Marketplace. Update this list when media is added to the device or when the user creates an "object" in the application (for example, a radio station is created or a music tag is created.)

• Apps contains the list of Music + Videos Hub applications that are installed on the device. The application submission and certification process will detect that you are calling the MediaHistory and MediaHistoryItem APIs and will set the HubType for your application. This will cause your application to appear in this list after it is installed on the device.

Your Music + Videos Hub application must conform to the Application Certification Requirements for Windows Phone to integrate with the Music + Videos Hub. The Windows Phone Marketplace submission process detects the use of the Music + Videos Hub APIs and grants access to the application using the Windows Phone application manifest.

Tiles that are displayed in the Music + Videos Hub must conform to additional iconography rules:

1. You must include your application title or logo on each Tile.

2. The now playing Tile must be 358 pixels x 358 pixels. The file size must be 75 KB or less.

3. Other tiles must be 173 pixels x 173 pixels in size.

4. The Title property of the MediaHistoryItem class must be set to text that represents the content, such as a station name or video title.

To help avoid confusion for users, Hub Tiles should not contain album art unless the album plays when the Hub Tile is pressed. If your application plays a stream, the Hub Tile graphic should describe the stream that is being played. While this is not a certification requirement, it is a good practice.

As your application must pass through the application submission and certification process in Windows Phone Marketplace before it can integrate into the Music + Videos Hub, you can use a workaround for testing purposes. In the Application Manifest File for Windows Phone, ensure that the HubType value is set to 1. The following code example shows how to set the HubType value.

<App xmlns="" ProductID=" {00000000-0000-0000-0000-000000000000} 
     Title="WindowsPhoneApplication" RuntimeType="Silverlight" 
     Version="1.0.0.0" Genre="NormalApp" Author="" Description="" 
     Publisher="" HubType="1">

For the current release, it is not possible to test Music + Videos Hub integration on Windows Phone Emulator. You must test Music + Videos Hub integration on a physical phone device.

If you attempt to update the Music + Videos Hub Tiles while the phone syncs with the Zune software, the APIs will throw an exception.

The following code example shows how to update the now playing Tile of the history list using the MediaHistory and MediaHistoryItem classes:

MediaHistoryItem mediaHistoryItem = new MediaHistoryItem();

//<hubTileImageStream> must be a valid ImageStream.
mediaHistoryItem.ImageStream = <hubTileImageStream>; 
mediaHistoryItem.Source = "";
mediaHistoryItem.Title = "NowPlaying";
mediaHistoryItem.PlayerContext.Add("keyString", "Song Name");
MediaHistory.Instance.NowPlaying = mediaHistoryItem;

The following code example shows how to update other Tiles besides the now playing Tile in the history list using the MediaHistory and MediaHistoryItem classes:

MediaHistoryItem mediaHistoryItem = new MediaHistoryItem();

//<hubTileImageStream> must be a valid ImageStream.
mediaHistoryItem.ImageStream = <hubTileImageStream>; 
mediaHistoryItem.Source = "";
mediaHistoryItem.Title = "RecentPlay";
mediaHistoryItem.PlayerContext.Add("keyString", "Song Name");
MediaHistory.Instance.WriteRecentPlay(mediaHistoryItem);

The following code example shows how to update the new list using the MediaHistory and MediaHistoryItem classes:

MediaHistoryItem mediaHistoryItem = new MediaHistoryItem();

//<hubTileImageStream> must be a valid ImageStream.
mediaHistoryItem.ImageStream = <hubTileImageStream>; 
mediaHistoryItem.Source = "";
mediaHistoryItem.Title = "MediaHistoryNew";
mediaHistoryItem.PlayerContext.Add("keyString", "Song Name");
MediaHistory.Instance.WriteAcquiredItem(mediaHistoryItem);

The following code example shows how to determine whether the application was launched from an item in the history or new list. This is done in the OnNavigatedTo(NavigationEventArgs) event handler. The information in the NavigationContext is used to determine the media associated with the item, in this case, a song from the media library on the device. The song starts playing in the Loaded event handler for the PhoneApplicationPage after the page has finished loading. For more information about this, see the Music and Videos Hub Sample.

bool _historyItemLaunch = false;            // Indicates whether the app was launched from a MediaHistoryItem.
const String _playSongKey = "keyString";    // Key for MediaHistoryItem key-value pair.
Song _playingSong = null;                   // The song to play.

protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
    MediaLibrary library = new MediaLibrary();

    if (NavigationContext.QueryString.ContainsKey(_playSongKey))
    {
        // We were launched from a history item.
        // Change _playingSong even if something was already playing 
        // because the user directly chose a song history item.

        // Use the navigation context to find the song by name.
        String songToPlay = NavigationContext.QueryString[_playSongKey];

        foreach (Song song in library.Songs)
        {
            if (0 == String.Compare(songToPlay, song.Name))
            {
                _playingSong = song;
                break;
            }
        }

        // Set a flag to indicate that we were started from a 
        // history item and that we should immediately start 
        // playing the song after the UI has finished loading.
        _historyItemLaunch = true;
    }
}

private void PhoneApplicationPage_Loaded(object sender, RoutedEventArgs e)
{
    if (_historyItemLaunch)
    {
        // We were launched from a history item, start playing the song.
        if (_playingSong != null)
        {
            MediaPlayer.Play(_playingSong);
        }
    }
}

Reference

Other Resources