How to integrate with the Music and Videos Hub for Windows Phone 8
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
The Music + Videos Hub is a focal point for all music, video, and podcast activity on a Windows Phone. Apps in the Music + Videos Hub provide an integrated music and video experience on the phone to help ensure a consistent end-user experience for media playback. See the Music and Videos Hub Sample for an example of an app that integrates with the Music + Videos Hub.
To appear as an app in the Music + Videos Hub, your app has to meet the following conditions:
Your app has to meet the certification requirements listed below.
Your app has to use the MediaHistory and MediaHistoryItem classes.
After your app passes through the app submission and certification process in Windows Phone Dev Center, the following things happen:
The app submission and certification process detects that you are calling the MediaHistory and MediaHistoryItem APIs and grants your app the security capabilities needed to call these APIs.
The certification process also sets the HubType for your app. As a result, your app automatically shows up in the apps list in the Music + Videos Hub after it is installed on a device.
Music + Videos Hub architecture
The Music + Videos Hub have five pages:
collection is the launch point for music, videos, podcasts, and Store. The Play button at the bottom of the page plays the entire music collection in shuffle mode.
history contains recently played music, videos, playlists, artists, podcasts, and content from third-party providers. Update this list when your Music + Videos Hub app plays media.
new contains an updated list of new music, videos, or podcasts synced to the phone or downloaded from XBox Music Store. Update this list when media is added to the device or when the user creates an "object" in the app (for example, when a music tag is created.)
apps contains the list of Music + Videos Hub apps that are installed on the device.
xbox contains links the Xbox Companion and the Xbox Music Store.
App certification requirements
Your Music + Videos Hub app must conform to the App certification requirements for Windows Phone to integrate with the Music + Videos Hub. The Dev Center submission process detects the use of the Music + Videos Hub APIs and grants access to the app through the Windows Phone app manifest.
Tiles that are displayed in the Music + Videos Hub must conform to additional iconography rules:
You must include your app title or logo on each Tile.
The now playing Tile must be 358 pixels x 358 pixels. The file size must be 75 KB or less.
Other tiles must be 173 pixels x 173 pixels in size.
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 app 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.
Testing Music + Videos Hub integration
As your app must pass through the app submission and certification process in Dev Center before it can integrate into the Music + Videos Hub, you can use a workaround for testing purposes. In the App manifest file for Windows Phone 8, ensure that the HubType value is set to 1. The following code example shows how to set the HubType value.
<App ProductID="{00000000-0000-0000-0000-000000000000}"
Title="WindowsPhoneApplication" RuntimeType="Silverlight"
Version="1.0.0.0" Genre="NormalApp" Author="" Description=""
Publisher="" PublisherID="" HubType="1">
Updating the 'now playing' Tile of the 'history' list
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;
Updating the 'history' list
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);
Updating the 'new' list
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);
Playing an item when launched from the 'history' or 'new' list
The following code example shows how to determine whether the app 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 example, the item is 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);
}
}
}