Nokia Music API

Recently, at the MWC-2013 conference, we presented our new phones. In addition, another news was announced, not least important for software developers. We are opening new APIs for third-party developers: Photo API, Nokia Music API and Maps API. Today we will talk about Nokia Music Windows Phone API . Nokia Music Windows Phone API provides an application with easy access to the latest information on millions of tracks from all over the world.




')
Thanks to Nokia Music Windows Phone API, the application can get a number of important advantages:
• Coverage.
• Simplify.
• API contracts "bottom-up compatible."

Coverage:
• helps users search for music of interest to them;
• provides detailed information about the piece of music that the user is interested in.
• Allows access to approximately 200 million tracks in more than 200 countries from nearly 3 million local and international artists.

Simplify application development:
The main task of Music Api is to collect and, more importantly, support the relevance of facts about tens of millions of tracks from record labels and aggregators. Without it, you would have to spend a lot of time in order to collect, verify, standardize and ensure the relevance of this data.

API compatibility:
The Music REST API contract contract is designed with a simple fact in mind - you can always learn something new about music.
The API contract allows you to add additional elements at any time without the need to introduce a new version of the API contract. But more importantly, if you follow the guidelines and recommendations described in this article, you will not have to release a new version of the application, its users will automatically get access to new features.

Let's look at the capabilities of the API using the example of the Music Explorer application.

You can download the application itself and its source code here: link .
The Music Explorer demonstrates the Nokia Music API use cases with standard Windows Phone 8 audio features. The application uses Nokia Music API features such as searching by artist name, requesting top artists and new releases, and launching Nokia Music from another application to play. Mix Radio or view artist info or songs.

Unlike browsers like Nokia Music Lite, to view artists and songs Music Explorer using Nokia Music API features interacts with music on the device in various ways. Favorite performers are sorted by listening frequency, the list of recommended performers is sorted according to the number of matches with the “Favorite” list. In addition, you can listen to tracks stored on the device.

Design and interface:
The main panorama of Music Explorer, shown below, contains six points: Favorites, Recommended, New, Top, Genres and Mixes.



Click image to enlarge

“Favorites” shows 20 performers whose compositions are most often played on the device, as well as their images obtained using the Nokia Music API. "Recommended" also offers a list of the most similar artists, sorted by similar criteria. "New" and "Top" show the last 10 tracks and the top 10 artists from the service "Music Nokia". “Genres” and “Mixes” also display the corresponding lists from the Nokia Music service. The list of genres and mixes depends on the current country of residence, and their names are given in the appropriate language. For this service uses the location data of the device.

The other main component of the user interface is the executor block, shown below. You can get into it by selecting an artist from “Favorites”, “Recommended”, “Top-10” list or genres list. The artist block is used to view the products available in the Nokia Music service for a specific artist. Using Nokia Music API you cannot buy products, so in this case the Nokia Music application opens, where you can buy the selected track. Also, the artist’s block allows you to launch this artist’s mix in Nokia Music or listen to its tracks stored on your device.



Nokia Music Api can be used to launch the Nokia Music service from another application. The service can be launched on the view tab of a specific artist or song (mix, track, album or single). In addition, you can start the service already on the playback of the selected mix. The note symbol is displayed in the Music Explorer in the event that interaction with the marked object leads to the launch of Nokia Music. Below are the “Genres” and “Mixes” pages, which are opened at the user's choice.



Architecture and implementation:
Music Explorer is a simple application that implements the pattern “model - view - view model (MVVM). This template allows you to separate data and user interface and is widely used in developing applications for Windows Phone 8. In the application, the model (data) are C # classes, and the view (user interface) is a set of PhoneApplicationPages, filled with WP8 controls. The MainViewModel, which connects the models and the view, is also a C # class. It is installed as a DataContext for all application pages to provide data binding. You can learn more about MVVM here , as well as using the list of links in the "See also" section at the bottom of the page. To view a more detailed architectural description of Music Explorer, you can visit the Implementation of this project page on Wiki.

Here is a table of the most significant APIs used by Music Explorer, as well as their capabilities:



The following Music Explorer services are provided by the Nokia Music API:



To use the Nokia Music API, the application will need a unique app ID and app token (if you are not going to use only launchers). They can be obtained by registering on the API registration page and requesting credentials for the Nokia Music API. App ID and app token for Music Explorer are listed in MusicApi.cs:

namespace MusicExplorer { ... public class MusicApi { // Constants public const string MUSIC_EXPLORER_APP_ID = "music_explorer_private_app_id"; // real app id not shown here public const string MUSIC_EXPLORER_APP_TOKEN = "music_explorer_private_app_token"; // real app token not shown here ... } } 

The application for WP8 should also have links to the current Nokia Music API client, which, in turn, requires a link to the JSON.Net library to add it to the application.
Instructions for adding necessary links are in the release_notes.txt file in the source code of the Music Explorer project .

Localization of Nokia Music API:
Before making a request to the Nokia Music API, Music Explorer checks the availability of the Nokia Music service for a specific country, which is implemented using the Windows Phone Location API. By default, Nokia Music API uses (and checks) the region settings in the phone with each API request. This allows the user to receive relevant, partially translated and based on the country of his or her information. This can be seen in the above panorama image showing the genres and mixes available for Finland, as well as the top Finnish artists at the moment. This list will look different if another valid country code is used when calling the Nokia Music API (for example, de for Germany or gb for UK).

 using Nokia.Music.Phone; ... namespace MusicExplorer { ... public partial class MainPage : PhoneApplicationPage { ... private CountryResolver resolver = null; ... private void InitializeNokiaMusicApi(string twoLetterCountryCode) { if (resolver == null) { resolver = new CountryResolver(MusicApi.MUSIC_EXPLORER_APP_ID, MusicApi.MUSIC_EXPLORER_APP_TOKEN); } resolver.CheckAvailability((Response<bool> response) => { Deployment.Current.Dispatcher.BeginInvoke(() => { if (response.Result) { // Make initial requests to fill models. App.MusicApi.Initialize(twoLetterCountryCode); ... } else { MessageBox.Show("Sorry, Nokia Music is not available in this locale."); } }); }, twoLetterCountryCode.ToLower()); } } } 

Create a client:
In Music Explorer, communication with the Nokia Music API, with the exception of CountryResolver described above, is enclosed in the MusicApi class for easy reference. All requests to the Nokia Music service are made using the MusicClient class, and therefore the next step after confirming the availability of the Nokia Music service is to create a MusicClient in the Initialize MusicApi method.

 using Nokia.Music.Phone; using Nokia.Music.Phone.Types; ... namespace MusicExplorer { ... public class MusicApi { ... // Members private MusicClient client = null; private bool initialized = false; ... public void Initialize(string countryCode) { // Create a music client with correct AppId and Token/AppCode if (countryCode == null || countryCode.Length != 2) { client = new MusicClient(MUSIC_EXPLORER_APP_ID, MUSIC_EXPLORER_APP_TOKEN); } else { client = new MusicClient(MUSIC_EXPLORER_APP_ID, MUSIC_EXPLORER_APP_TOKEN, countryCode.ToLower()); } initialized = true; } ... } } 

Making requests:
Requests to the Nokia Music service can be sent after creating a localized MusicClient example. For example, the GetTopArtists method from MusicApi queries the 10 most popular artists in the Nokia Music service (for the country with the code that MusicClient was launched) and fills the TopArtists from the MainViewModel with relevant information. The Who's in Top view panorama uses links to display TopArtists in the user interface. Since the remaining requests (new releases, genres, etc.) are similar, we will not consider them separately. You can view the project page for links to specific examples.

 namespace MusicExplorer { ... public class MusicApi { ... // Members private MusicClient client = null; private bool initialized = false; ... public void GetTopArtists() { if (!initialized) { return; } client.GetTopArtists((ListResponse<Artist> response) => { Deployment.Current.Dispatcher.BeginInvoke(() => { // Use results if (response != null && response.Result != null && response.Result.Count > 0) { App.ViewModel.TopArtists.Clear(); foreach (Artist a in response.Result) { if (a.Thumb100Uri != null) { App.ViewModel.TopArtists.Add(new ArtistModel() { Name = a.Name, Country = CountryCodes.CountryNameFromTwoLetter(a.Country), Genres = a.Genres[0].Name, ThumbUri = a.Thumb100Uri, Id = a.Id }); } else { App.ViewModel.TopArtists.Add(new ArtistModel() { Name = a.Name, Country = CountryCodes.CountryNameFromTwoLetter(a.Country), Genres = a.Genres[0].Name, ThumbUri = new Uri("/Assets/thumb_100_placeholder.png", UriKind.Relative), Id = a.Id }); } } } if (response != null && response.Error != null) { ShowNokiaMusicApiError(); } HideProgressIndicator("GetTopArtists()"); }); }); ShowProgressIndicator("GetTopArtists()"); } ... } } 

Nokia Music Launchers:
The following method from MusicApi Music Explorer shows how easy it is to launch the Nokia Music service to play the artist’s mix. The service can be opened on the work or artist page using the Nokia Music API. Some launcher methods in the Nokia Music API require a unique artist, mix or work ID. IDs can be obtained in response to requests from other Nokia Music Api services.

 using Nokia.Music.Phone; using Nokia.Music.Phone.Tasks; ... namespace MusicExplorer { ... public class MusicApi { ... public void LaunchArtistMix(string artistName) { ... PlayMixTask task = new PlayMixTask(); task.ArtistName = artistName; task.Show(); } ... } } 

Local music as a starting point:
The list of artists in the Favorite is created by the LoadData MainViewModel method. Comments in the code describe the steps taken to create the list.

 using Microsoft.Xna.Framework.Media; ... namespace MusicExplorer.Models { ... public class MainViewModel : INotifyPropertyChanged { ... public ObservableCollection<ArtistModel> LocalAudio { get; private set; } ... MediaLibrary mediaLib = null; //       . ... public MainViewModel() { LocalAudio = new ObservableCollection<ArtistModel>(); ... //     LocalAudio.Add(new ArtistModel() { Name = "MusicExplorerTitlePlaceholder", ItemHeight = "110", ItemWidth = "400" }); } ... public void LoadData() { mediaLib = new MediaLibrary(); ... foreach (Artist a in mediaLib.Artists) { if (a.Songs.Count <= 0) continue; //     string artist = a.Name; int trackCount = a.Songs.Count; int playCount = 0; //      foreach (Song s in a.Songs) { playCount += s.PlayCount; } //     . bool artistAdded = false; for (int i = 1; i < LocalAudio.Count; i++) // Index 0     { if (Convert.ToInt16(LocalAudio[i].PlayCount) < playCount) { this.LocalAudio.Insert(i, new ArtistModel() { Name = artist, LocalTrackCount = Convert.ToString(trackCount), PlayCount = Convert.ToString(playCount) }); artistAdded = true; break; } } // ...     ,      . if (artistAdded == false) { this.LocalAudio.Add(new ArtistModel() { Name = artist, LocalTrackCount = Convert.ToString(trackCount), PlayCount = Convert.ToString(playCount) }); } ... } // ,   -20   int removeIndex = App.ViewModel.LocalAudio.Count - 1; while (removeIndex > 20) { App.ViewModel.LocalAudio.RemoveAt(removeIndex); removeIndex--; } //      « » foreach (ArtistModel m in App.ViewModel.LocalAudio) { if (m.Name == "MusicExplorerTitlePlaceholder") continue; if (Convert.ToInt16(m.LocalTrackCount) > (totalTrackCount / totalArtistCount)) { m.ItemHeight = "200"; m.ItemWidth = "206"; } else { m.ItemHeight = "100"; m.ItemWidth = "206"; } } ... } ... } } 

After creating a list of selected artists, a database is searched using the Nokia Music API to create a list of “similar” for each of them. Then this list is built in accordance with the number of auditions of performers on which a list of similar ones was built. In addition, performers with songs stored on the device are excluded from the list, since the main idea is to promote new music.

In the next article we will look at working with the Advanced photo capturing API.