Media Playback

To play songs, audio books and audio podcasts from a device iPod library, you use a ISN_MediaController class. In a nutshell the steps to perform are as follows:

  • Register to receive music player notifications and turn on notifications
  • Create a music player
  • Set up a playback queue for the music player
  • Configure the playback options
  • Invoke playback

This chapter describes how to implement these steps. It also provides guidance for handling some scenarios you may encounter while using a music player.

You also need to enable Media Player API with IOS Native Settings.

Registering for Music Player Notifications

If you provide music player playback control or if you display information about the now-playing item, you must register for music player notifications as shown in listing below:

ISN_MediaController.ActionQueueUpdated += HandleActionQueueUpdated;
ISN_MediaController.ActionPlaybackStateChanged += HandleActionPlaybackStateChanged;
ISN_MediaController.ActionNowPlayingItemChanged += HandleActionNowPlayingItemChanged;

void HandleActionNowPlayingItemChanged (MP_MediaItem item) {
	Debug.Log("Now Playing Item Changed: " + ISN_MediaController.Instance.NowPlayingItem.Title);

void HandleActionPlaybackStateChanged (MP_MusicPlaybackState state) {
	Debug.Log("Playback State Changed: " + ISN_MediaController.Instance.State.ToString());

void HandleActionQueueUpdated (List<MP_MediaItem> items) {
	foreach(MP_MediaItem item in items) {
		Debug.Log("Item: " + item.Title + " / " + item.Id);

Configuring a Music Player

As the listing shows, you may also want to configure shuffle and repeat modes so that they do not take on the iPod modes of apps—which they would do by default. The various shuffle and repeat modes are described in MP_MusicRepeatMode and MP_MusicShuffleMode


Setting Up a Playback Queue

There are two main ways to set up a playback queue for a music player:

  • Use a native ios media item selector UI to allow user select items manually from the music library
  • Set media items collection programmatically

You can display native media picker and subscribe for result as showed in the code snippet below. The result is represented as the MP_MediaPickerResult object.

ISN_MediaController.ActionMediaPickerResult += HandleActionMediaPickerResult;

void HandleActionMediaPickerResult (MP_MediaPickerResult res) {
	if(res.IsSucceeded) {
		Debug.Log("Media piacker Succeeded");
	} else {
		Debug.Log("Media piacker failed: " + res.Error.Description);

Note:  If a user has selected at least one song, the current player queue will be updated to meet the selection. It means that  ActionQueueUpdated will be fired as well.

You can Playback Queue programmatically using SetCollection method of the ISN_MediaController.

//Set's playback queue with the specified media items 
public void SetCollection(params MP_MediaItem[] items);

//Set's playback queue using media items id's
public void SetCollection(string[] itemIds);

For example, you have a race game, and your user should specify a list of songs which can be played during the race (or specify different song for different tracks).  You do not want it to select it manually each time. So, as soon as he has selected at least one song, you can store selected MP_MediaItem's  id's using, for example PlayerPrefs. And when a user launches the game next time, you can set a queue of players using earlier stored ids.

If some of provided ids are incorrect (for example, a user has already removed media item from the device) those ids / media items will be ignored. SetCollection method call will trigger  ActionQueueUpdated event, and you will be able to get MP_MediaItem's list which was successfully loaded to the current player queue. The current player queue is always available with the following getter:


As well as now playing item:


The code snippet below will show how to cut all items from current player queue (assuming we have at least an item in queue) instead of the first item in queue.


Controlling Playback

Playback control for music players is straightforward as described in ISN_MediaControllerClass Reference. You can:

  • Play
  • Pause
  • Skip To Beginning
  • Skip To Next Item
  • Skip To Previous Item

Privacy Settings in iOS 10

It has long been the case with iOS that if you want to access a user’s private data, first, you need ask the user for permission. In iOS 10 Apple is extending the scope of these privacy controls by including access to the user’s photo library, camera, media player, etc. A list of affected frameworks can be found below:

Contacts, Calendar, Reminders, Photos, Bluetooth Sharing, Microphone, Camera, Location, Health, HomeKit, Media Library, Motion, CallKit, Speech Recognition, SiriKit, TV Provider.

It means that if you want to use Media Player API, you need to provide purpose string to a user. You can specify that string using IOS Native Settings menu as showed below:


Or you can also do this using the following variables:


The system shows the purpose string when asking the user to allow access (so you may want to localize it):

The direction from Apple is clear. If you access private data, declare your intentions up front or expect your App to crash.

API Reference


public class ISN_MediaController : ISN_Singleton<ISN_MediaController> {

	// Actions

	//Posted when medial picker is closed with result
	public static event Action<MP_MediaPickerResult> ActionMediaPickerResult;

	//Posted when the current playing queue  updated
	public static event Action<List<MP_MediaItem>> ActionQueueUpdated;

	//Posted when the currently playing media item has changed
	public static event Action<MP_MediaItem> ActionNowPlayingItemChanged;

	//Posted when the playback state has been changed programmatically or by user action. 
	public static event Action<MP_MusicPlaybackState> ActionPlaybackStateChanged;

	// Public Methods

	//Set's the current repeat mode of the music player.
	public void SetRepeatMode(MP_MusicRepeatMode mode);

	//Set's the current shuffle mode of the music player
	public void SetShuffleMode(MP_MusicShuffleMode mode);

	//Initiates playback of the current item. 
	//If playback was previously paused, this method resumes playback where it left off; 
	//otherwise, this method plays the first available item, from the beginning.
	public void Play();

	//Pauses playback of the current item. 
	//If playback is not currently underway, this method has no effect. 
	//To resume playback of the current item from the pause point, call the play method.
	public void Pause();

	//Starts playback of the next media item in the playback queue; 
	//or, the music player is not playing, designates the next media item as the next to be played.
	//If already at the last item in the playback queue when this method is called, ends playback.
	public void SkipToNextItem();

	//Restarts playback at the beginning of the currently playing media item.
	public void SkipToBeginning();

	//Starts playback of the previous media item in the playback queue; 
	//or, the music player is not playing, designates the previous media item as the next to be played.
	//If already at the first item in the playback queue when this method is called, ends playback.
	public void SkipToPreviousItem();

	//Shows IOS media picker
	public void ShowMediaPicker();

	//Set's playback queue with the specified media items 
	public void SetCollection(params MP_MediaItem[] items);

	//Set's playback queue using media items id's
	public void SetCollection(params string[] itemIds);

	// Get / Set

	//The currently-playing media item, or the media item, within a queue, that you have designated to begin playback with.
	public MP_MediaItem NowPlayingItem { get;}
	//Current playback queue media items
	public List<MP_MediaItem> CurrentQueue{ get;}

	//The current playback state of the music player.
	public MP_MusicPlaybackState State{ get;}



public class MP_MediaItem {

	//The persistent identifier for the media item. 
	public string Id {get;}

	//The title (or name) of the media item
	public string Title {get;}

	//The performing artist(s) for a media item—which may vary from the primary artist for the album that a media item belongs to. 
	//For example, if the album artist is “Joseph Fable,” the artist for one of the songs in the album may be 
	//“Joseph Fable featuring Thomas Smithson”.
	public string Artist {get;}

	//The title of an album, such as “Live On Mars”, 
	//as opposed to the title of an individual song on the album, such as “Crater Dance (radio edit)”
	public string AlbumTitle {get;}

	//The primary performing artist for an album as a whole. 
	public string AlbumArtist {get;}

	//The musical or film genre of the media item.
	public string Genre {get;}

	//The musical composer for the media item.
	public string Composer {get;}


public class MP_MediaPickerResult : ISN_Result {
	//Items selected by user from the media picker
	public List<MP_MediaItem> SelectedmediaItems {get;}


public enum MP_MusicPlaybackState  {
	Stopped = 0,
	Playing = 1,
	Paused = 2,
	MPMInterrupted= 3,
	SeekingForward = 4,
	SeekingBackward = 5


public enum MP_MusicRepeatMode  {
	Default = 0,
	None = 1,
	One = 2,
	All = 3


public enum MP_MusicShuffleMode  {
	Default = 0,
	Off = 1,
	Songs = 2,
	Albums = 3