Недавно на конференции MWC-2013 мы представили свои новые телефоны. Кроме того, была озвучена еще одна новость, немаловажная в первую очередь для разработчиков программного обеспечения. Мы открываем новые API для сторонних разработчиков: Photo API, Nokia Music API и Maps API. Сегодня мы расскажем о Nokia Music Windows Phone API. Nokia Music Windows Phone API обеспечивает приложению простой доступ к самой свежей информации о миллионах треков со всех уголков земного шара.
Благодаря Nokia Music Windows Phone API приложение может получить ряд важных преимуществ:
• Охват.
• Упрощение.
• Контракты API, «совместимые снизу вверх».
Охват:
• помогает пользователям искать интересующую их музыку;
• предоставляет детальную информацию о том музыкальном произведении, которым интересуется пользователь.
• Позволяет получать доступ к примерно 200 миллионам треков в более чем 200 странах мира от почти 3 миллионов местных и международных исполнителей.
Упрощение разработки приложения:
Основная задача Music Api — сбор и, что более важно, поддержка актуальности фактов о десятках миллионов треков от рекорд-лейблов и агрегаторов. Без него вам пришлось бы потратить немало времени для того, чтобы собрать, проверить, стандартизировать и обеспечить актуальность этих данных.
Совместимость с API:
API-контракт Music REST API разработан с учетом простого факта — о музыке всегда можно узнать что-то новое.
Контракт API позволяет вносить дополнительные элементы в любое время без необходимости вводить новую версию контракта API. Но более важно то, что, если следовать указаниям и рекомендациям, описанным в этой статье, не придется выпускать новую версию приложения, его пользователи автоматически получат доступ к новым функциям.
Давайте рассмотрим возможности API на примере приложения Music Explorer.
Вы можете загрузить само приложение и его исходный код здесь: ссылка.
Music Explorer демонстрирует варианты использования Nokia Music API со стандартными аудиовозможностями Windows Phone 8. Приложение использует такие возможности Nokia Music API, как поиск по имени исполнителя, запрос топа исполнителей и новых релизов, а также запуск приложения «Музыка Nokia» из другого приложения для проигрывания «Микс радио» или просмотра информации об исполнителе или композиции.
В отличие от браузеров вроде Nokia Music Lite, для просмотра исполнителей и композиций Music Explorer с помощью возможностей Nokia Music API взаимодействует с музыкой на устройстве различными способами. Любимые исполнители сортируются по частоте прослушивания, список рекомендуемых исполнителей сортируется согласно количеству совпадений со списком «Избранного». Кроме того, можно прослушивать треки, сохраненные на устройстве.
Дизайн и интерфейс:
Основная панорама Music Explorer, показанная ниже, содержит шесть пунктов: «Избранное», «Рекомендованное», «Новинки», «Топ», «Жанры» и «Миксы».
Нажмите картинку для увеличения
«Избранное» показывает 20 исполнителей, чьи композиции наиболее часто проигрываются на устройстве, а также их изображения, полученные с помощью Nokia Music API. «Рекомендованное» же предлагает список наиболее похожих исполнителей, отсортированных по аналогичному критерию. «Новинки» и «Топ» показывают 10 последних композиций и топ-10 исполнителей из сервиса «Музыка Nokia». «Жанры» и «Миксы» также отображают соответствующие списки из сервиса «Музыка Nokia». Список жанров и миксов зависит от текущей страны пребывания, а их названия приведены на соответствующем языке. Для этого сервис использует данные о местоположении устройства.
Другим основным компонентом пользовательского интерфейса является блок исполнителя, показанный ниже. Попасть в него можно, выбрав исполнителя из «Избранного», «Рекомендованного», списка «топ-10» или списка жанров. Блок исполнителя используется для просмотра продуктов, доступных в сервисе «Музыка Nokia» для конкретного исполнителя. С помощью Nokia Music API нельзя приобретать продукты, поэтому в данном случае открывается приложение «Музыка Nokia», в котором выбранный трек можно будет купить. Также блок исполнителя позволяет запустить микс этого исполнителя в «Музыке Nokia» или прослушать его треки, сохраненные на устройстве.
Nokia Music Api может быть использован для запуска сервиса «Музыка Nokia» из другого приложения. Сервис может быть запущен на вкладке просмотра определенного исполнителя или композиции (микса, трека, альбома или сингла). Кроме того, можно запустить сервис уже на проигрывании выбранного микса. Символ «нота» отображается в Music Explorer в том случае, если взаимодействие с отмеченным объектом приведет к запуску «Музыки Nokia». Ниже показаны страницы «Жанры» и «Миксы», которые открываются по выбору пользователя.
Архитектура и реализация:
Music Explorer является простым приложением, реализующим шаблон «модель — вид — модель вида (MVVM). Данный шаблон позволяет разделить данные и пользовательский интерфейс и широко применяется при разработке приложений под Windows Phone 8. В приложении модель (данные) — это классы C#, а вид (пользовательский интерфейс) является набором PhoneApplicationPages, заполненных с помощью контролов WP8. MainViewModel, который соединяет модели и вид, — это тоже класс С#. Он устанавливается как DataContext для всех страниц приложений для обеспечения привязки данных. Узнать больше о MVVM можно здесь, а также воспользовавшись списком ссылок раздела «Смотри также» в низу страницы. Для просмотра более детального архитектурного описания Music Explorer можно посетить страницу Реализация данного проекта в Wiki.
Вот таблица самых значимых API, используемых Music Explorer, а также их возможности:
Следующие используемые Music Explorer сервисы предоставляются Nokia Music API:
Для использования Nokia Music API приложению потребуется уникальный app ID и app token (если вы не собираетесь использовать только лончеры). Они могут быть получены при регистрации на странице регистрации API и запросе полномочий для Nokia Music API. App ID и app token для Music Explorer указаны в 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
...
}
}
Приложение для WP8 должно также иметь ссылки на актуальный клиент Nokia Music API, который, в свою очередь, требует ссылку на библиотеку JSON.Net для добавления ее в приложение.
Инструкции по добавлению необходимых ссылок находятся в файле release_notes.txt в исходниках проекта Music Explorer.
Локализация Nokia Music API:
Перед тем как сделать запрос к Nokia Music API, Music Explorer проверяет доступность сервиса «Музыка Nokia» для конкретной страны, что реализовано с помощью Windows Phone Location API. По умолчанию Nokia Music API использует (и проверяет) настройки региона в телефоне при каждом запросе к API. Это позволяет пользователю получать соответствующую, частично переведенную и основанную на стране нахождения информацию. Это можно увидеть на изображении панорамы выше, показывающей жанры и миксы, доступные для Финляндии, также как топ финских исполнителей на текущий момент. Этот список будет выглядеть иначе, если будет использован другой валидный код страны при вызове Nokia Music API (например de для Германии или gb для Великобритании).
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());
}
}
}
Создаем клиент:
В Music Explorer коммуникация с Nokia Music API, за исключением описанного выше использования CountryResolver, заключена в класс MusicApi для простого обращения. Все запросы к сервису «Музыка Nokia» осуществляются с использованием класса MusicClient, и поэтому следующим шагом после подтверждения доступности сервиса «Музыка Nokia» будет создание MusicClient в методе Initialize MusicApi.
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;
}
...
}
}Делаем запросы:
Запросы к сервису Nokia Music могут быть отправлены после создания локализованного примера MusicClient. Например, метод GetTopArtists из MusicApi запрашивает 10 наиболее популярных исполнителей в сервисе «Музыка Nokia» (для страны, с кодом которой был запущен MusicClient) и заполняет TopArtists из MainViewModel соответствующей информацией. Панорама «Кто в топе» использует связи для отображения TopArtists в пользовательском интерфейсе. Поскольку остальные запросы (новые релизы, жанры и т.д.) аналогичны, мы их не будем рассматривать отдельно. Вы можете посмотреть страницу проекта для получения ссылок на конкретные примеры.
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:
Следующий метод из MusicApi Music Explorer'а показывает, как просто запустить сервис «Музыка Nokia», чтобы воспроизвести микс исполнителя. Сервис может быть открыт на странице произведения или исполнителя с использованием Nokia Music API. Некоторые методы лончера в Nokia Music API требуют уникальные ID исполнителя, микса или произведения. ID могут быть получены в ответ на запросы других служб Nokia Music Api.
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();
}
...
}
}Локальная музыка как отправная точка:
Список исполнителей в «Избранном» создается методом LoadData MainViewModel. Комментарии в коде описывают шаги, предпринятые для создания списка.
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";
}
}
...
}
...
}
}
После создания списка избранных исполнителей выполняется поиск по базе с использованием Nokia Music API для создания списка «похожих» для каждого из них. Затем этот список выстраивается в соответствии с количеством прослушиваний исполнителей по которым строился список схожих. Кроме того, исполнители с композициями, сохраненными на устройстве, исключаются из списка, поскольку основная идея состоит в продвижении новой музыки.
В следующей статье мы рассмотрим работу с Advanced photo capturing API.
Автор: nokiaman
