#backgroundmediaplayer

New Post has been published on http://drew5.net/2014/12/06/windows-phone-app-studio-soundcloud-api-part-2/

Windows Phone App Studio + SoundCloud API - Part 2

In the first part of the tutorial we just did the basics. Enter a collection in our App Studio project and add a service provider to communicate to SoundCloud API to “launch” the media to play. While it works, it is not as elegant as we would like.

In this part, we will build upon what we did with the first steps but add background audio so that our media plays when we navigate away from the app. Let’s jump in!

If you are following along then you can jump right in, if not, please take a look at the first part of this tutorial, there are a few items that are needed to really get going.

Step 1: Background on the Background Audio

A background audio app uses background agents. However, playing audio in the background in Windows Phone 8.1 is different from the way background audio is played in Windows 8. The model also differs from background audio agents used in earlier versions of Windows Phone.

The Windows.Media.Playback namespace introduces generic audio APIs and can be used to play music even in the foreground, but their primary purpose is to play audio in the background. When using this API, there is a single global MediaPlayer through which all playback occurs. Your background audio app sends commands to the media player to set the current track, start playback, pause, fast forward, rewind, and so on. You do this by calling methods on the MediaPlayer class. The media player instance object, accessed through the BackgroundMediaPlayer.Current property, communicates with the global media player to manipulate audio playback.

Taken straight from the MSDN site. Basically what this means is any app that is running a background playback is actually running 2 sets of process. The main app is the first process which runs in the foreground. The second is the task of running the background playback. The background task does the actually “playing” and can contain logic if needed. Communication happens between the two via proxy objects and notifications on “special” events.

Here is a diagram from MSDN that clarifies this a bit.

If you run Pandora, Spotify or XBOX Music you are already familiar with how apps work with the background player task.

One other major item to note: this tutorial is focusing only on Windows Phone Store apps, NOT Windows Store apps. The reason being is the big difference in playing background audio in a Windows Store app vs. Windows Phone 8 app. The use of the BackgroundAudioPlayer on the Phone and the MediaElement / Audio tag for Windows Store apps. The BackgroundAudioPlayer is a static class that can be used without needing instantiation. The MediaElement and Audio tags must be defined in markup before they can be used. In a future step I will circle back to discuss and show how we can implement something similar in Windows 8.1.

Step 2: Let’s Get Started

Before we dive into the code, lets discuss what we want to accomplish. Right now our app is using the Data Collection on App Studio to pull down a “Track” collection. This consists of an image, track name and url to the track. Our app displays this information in the Hub view of our main page. We now want to click on one of the track items to play the track instead of launching a new app to download the track and then play. In order to accomplish this there are a few things we are going to have to create.

The actual background audio task

A new page that will be our music player to start the background task

A change to the view model to go to our new page

A few changes to our SoundCloud service

In the AppStudio.WindowsPhone project, in the Views folder, lets add a Blank XAML file called MusicPlayer.xaml. This will be our music player and will be using a FlipView control to “flip” through all of our tracks.

<FlipView x:Name="Flip" Grid.Row="1" AutomationProperties.AutomationId="ItemsFlipView" AutomationProperties.Name="Item Details" TabIndex="1" DataContext="Binding TracksModel" d:DataContext="d:DesignData Source=/Assets/Data/TracksDataSource.json, Type=vm:TracksViewModel, IsDesignTimeCreatable=True" ItemsSource="Binding Items" SelectedItem="Binding SelectedItem, Mode=TwoWay" ItemContainerStyle="StaticResource FlipItemStyle"> <!-- TEMPLATE GOES HERE --> </FlipView>

Basically this is binding out FlipView to our TracksModel, similar to the detail page, but now we have to add our data template.

<FlipView.ItemTemplate> <DataTemplate> <ScrollViewer> <StackPanel> <TextBlock Margin="0,1" Text="Binding TrackTitle, Converter=StaticResource TextPlainConverter, ConverterParameter=140" Style="StaticResource SubHeaderText" /> <Image Margin="0, 8" Source="Binding Image, Converter=StaticResource ThumbnailConverter, ConverterParameter=220" Stretch="UniformToFill" VerticalAlignment="Top" /> </StackPanel> </ScrollViewer> </DataTemplate> </FlipView.ItemTemplate>

If you look, it is the same as our TrackDetail but contained in a FlipView.

We can now add the plumbing to make sure out FlipView is “flipping” through our data model. Open up the CS and we need to do some housecleaning first.

private NavigationHelper _navigationHelper; private DataTransferManager _dataTransferManager; public NavigationHelper NavigationHelper get return _navigationHelper; public TracksViewModel TracksModel get; private set;

Our standard members need to be added to our page which we can reference from our constructor and our navigated events.

public MusicPlayer() this.InitializeComponent(); _navigationHelper = new NavigationHelper(this); TracksModel = new TracksViewModel();

And

protected async override void OnNavigatedTo(NavigationEventArgs e) _dataTransferManager = DataTransferManager.GetForCurrentView(); _dataTransferManager.DataRequested += OnDataRequested; _navigationHelper.OnNavigatedTo(e); if (TracksModel != null) await TracksModel.LoadItemsAsync(); if (e.NavigationMode != NavigationMode.Back) TracksModel.SelectItem(e.Parameter); TracksModel.ViewType = ViewTypes.Detail; DataContext = this; protected override void OnNavigatedFrom(NavigationEventArgs e) _navigationHelper.OnNavigatedFrom(e); _dataTransferManager.DataRequested -= OnDataRequested;

The last step to get this to run is to update the TracksViewModel.cs ItemClickCommand to navigate to this page instead of the TracksDetail page. Now, remember, this tutorial will only work with the Windows Phone right now. Since the view model is in the “shared” project, in Windows it will also go to the new page.

If we compile and run our MusicPlayer page should show all of our tracks in our FlipView. We will come back to this page in a bit. We still need to add our player buttons and hooking up our background agent.

Step 3: Meet Agent Background

Ok, that was a bit corny but lets meet it anyway. Our agent really needs to consist of a few methods, a run, messages received from our foreground app, completed and canceled. There are others but those are the major ones to get this going. I am not going into super detail on the background agent. I will talk about a few of the methods and what is going on but it is better to grab the full source and put it in your project.

How do we create this background agent? Well we first need to add a new project. Do this by going to Add, New Project, Windows Phone Apps, Windows Runtime Component (Windows Phone). Name it BackgroundAudioTask. We are going to need 3 classes. 1: ApplicationSettingsHelper.cs 2: Constants.cs 3: BackgroundAudioTask.cs. If you want to just add those 3 files for now, keeping them empty is fine for now.  Open up our BackgroundAudioTask.cs and we need to implement a IBackground task and make sure our class is sealed.

public sealed class BackgroundAudioTask: IBackgroundTask ...

Once that is done we need to go to our Windows Phone project and add a reference to our BackgroundAudioTask component and then open up our AppManifest file. In there we need to declare a Background Task and define our entry point.

This will allow our app to initiate background tasks.

Grab the ApplicationSettingsHelper.cs and Constants.cs from GitHub and put those in your project. We will now look at a few methods in the BackgroundAudioTask.cs.

public void Run(IBackgroundTaskInstance taskInstance) { _systemMediaTransportControl = SystemMediaTransportControls.GetForCurrentView(); _systemMediaTransportControl.IsEnabled = true;

We are first supporting the Media Transport Control. It represents an object that enables integrate with the system media transport controls and support for media commands.

//Add handlers for MediaPlayer BackgroundMediaPlayer.MessageReceivedFromForeground += MessageReceivedFromForeground; //Initialize message channel BackgroundMediaPlayer.Current.CurrentStateChanged += BackgroundMediaPlayerCurrentStateChanged; // Associate a cancellation and completed handlers with the background task. taskInstance.Canceled += OnCanceled; taskInstance.Task.Completed += Taskcompleted;

Handlers all get initialized. Message from foreground listens to messages from our app, like play etc. Current state change handles any changes and reflects them back to the universal volume control.

var value = ApplicationSettingsHelper.ReadResetSettingsValue(Constants.AppState); if (value == null) foregroundAppState = ForegroundAppStatus.Unknown; else foregroundAppState = (ForegroundAppStatus)Enum.Parse(typeof(ForegroundAppStatus), value.ToString()); //Send information to foreground that background task has been started if app is active if (foregroundAppState != ForegroundAppStatus.Suspended) ValueSet message = new ValueSet(); message.Add(Constants.BackgroundTaskStarted, ""); BackgroundMediaPlayer.SendMessageToForeground(message); BackgroundTaskStarted.Set(); backgroundtaskrunning = true; ApplicationSettingsHelper.SaveSettingsValue(Constants.BackgroundTaskState, Constants.BackgroundTaskRunning); _deferral = taskInstance.GetDeferral();

The rest is setting/saving states for application to resume and cancel as well as kick of the background task.

private void MessageReceivedFromForeground(object sender, MediaPlayerDataReceivedEventArgs e) ValueSet valueSet = e.Data; foreach (string key in valueSet.Keys) switch (key.ToLower()) case Constants.StartPlayback: Debug.WriteLine("Starting Playback"); Play(valueSet[key].ToString()); break;

Messages that are sent from the foreground app will be handled by this event. A ValueSet (key/value) gets sent and depending upon what is sent, certain conditions can happen. In this case, play.

private void Play(string toPlay) '); MediaPlayer mediaPlayer = BackgroundMediaPlayer.Current; mediaPlayer.AutoPlay = true; mediaPlayer.SetUriSource(new Uri(trackInfo[0])); //Update the universal volume control _systemMediaTransportControl.ButtonPressed += MediaTransportControlButtonPressed; _systemMediaTransportControl.IsPauseEnabled = true; _systemMediaTransportControl.IsPlayEnabled = true; _systemMediaTransportControl.DisplayUpdater.Type = MediaPlaybackType.Music; _systemMediaTransportControl.DisplayUpdater.MusicProperties.Artist = trackInfo[1]; _systemMediaTransportControl.DisplayUpdater.MusicProperties.Title = trackInfo[2]; _systemMediaTransportControl.DisplayUpdater.Update();

Here is the meat and potatoes. Our Play. We set the URI to our Stream URL. Set our transport controls as well so we can view the proper information when we switch out from our app.

Now there are a lot more methods and handlers in the BackgroundAudioTask.cs but I am not going to go into detail with them. The code is commented and talks about what each one does. But this can now get your background task ready to receive info from the foreground app.

Step 4: Foreground App

We did some work for the foreground app but we need to a bit more customization. We have our TrackModel displaying on the music player page however we are not communicating with the background tasks. Lets first add a folder called BackgroundAudioHelper and add 2 linked files from the BackgroundAudioTask runtime project, Constants and ApplicationSettingsHelper. We are going to need them in our app. Next lets go into our SoundCloudSerivce.cs file and add a new method to return our TrackSchema object. Remember in part 1 we were just return the stream url, this time we will need the full object.

public static async Task<SoundCloudTrackSchema> GetTrackInfo(string trackUrl) try var serviceProvider = new AppStudio.Data.SoundCloudProvider(_clientId, trackUrl); return await serviceProvider.LoadTrack<SoundCloudTrackSchema>(); catch (Exception ex) AppLogs.WriteError("SoundCloudMusicService", ex.ToString()); return null;

Great. Now lets go back to our MediaPlayer.xaml and add some controls for playback.

<Page.BottomAppBar> <CommandBar> <AppBarButton x:Name="AppBarPrevButton" Icon="Previous" Label="Play" Click="PrevButton_Click"/> <AppBarButton x:Name="AppBarPlayButton" Icon="Play" Label="Play" Click="PlayButton_Click"/> <AppBarButton x:Name="AppBarRefreshButton" Icon="Refresh" Label="Start" Click="RefreshButton_Click"/> <AppBarButton x:Name="AppBarNextButton" Icon="Next" Label="Next" Click="NextButton_Click"/> </CommandBar> </Page.BottomAppBar>

Now that we have the service returning the full object, our xaml ready for the playback lets hook everything up.

In MediaPlayer.xaml.cs we will add a member to check if our background task is running or now.

private bool isBackgroundTaskRunning = false; /// <summary> /// Gets the information about background task is running or not by reading the setting saved by background task /// </summary> private bool IsBackgroundTaskRunning get if (isBackgroundTaskRunning) return true; object value = ApplicationSettingsHelper.ReadResetSettingsValue(Constants.BackgroundTaskState); if (value == null) return false; else isBackgroundTaskRunning = ((String)value).Equals(Constants.BackgroundTaskRunning); return isBackgroundTaskRunning;

Now lets attach a Play Click Event Handler.

private void PlayButton_Click(object sender, RoutedEventArgs e) System.Diagnostics.Debug.WriteLine("Play button pressed from App"); if (IsBackgroundTaskRunning) if (MediaPlayerState.Playing == BackgroundMediaPlayer.Current.CurrentState) //Audio is playing..need to Pause BackgroundMediaPlayer.Current.Pause(); else if (MediaPlayerState.Paused == BackgroundMediaPlayer.Current.CurrentState) //Audio is paused so start playing BackgroundMediaPlayer.Current.Play(); else if (MediaPlayerState.Closed == BackgroundMediaPlayer.Current.CurrentState) //No audio playing StartBackgroundAudio(); else StartBackgroundAudio();

First, it checks if the background audio task is running. If not, then just play the audio. If it is running then it checks what the current state of the media player is and performs the appropriate function.

private async void StartBackgroundAudio() SoundCloudTrackSchema trackSchema = await SoundCloudMusicService.GetTrackInfo(TracksModel.SelectedItem.TrackUrl.ToString()); ValueSet message = new ValueSet(); message.Add(Constants.StartPlayback, String.Format("0

And here is the Start method. We call our SoundCloudService to get the track object. We create a name value pair message to send to our BackgroundMediaPlayer. The message is the stream url and track name and artist name. The Play method in the task is smart to split that up. However, you can change that as you see fit.

That is it! Not really. There are handlers all over the place but they just help with resuming and canceling. There are a few events handlers helping with next and previous as well.

The project is updated out on GitHub. A few things that still need to be worked on

AutoPlay from one track to next track

The Universal Volume Control next and previous events

Updating image in the FlipView with the image from SoundCloud

Add the artist name in the FlipView from SoundCloud

Update the images in the main view with images from SoundCloud.

Get all of this to work with Windows 8.1 Store apps.