The Apple Media Service is a Bluetooth Low Energy (BLE) service that allows BLE devices, such as Apple Watches and remote controls, to interface with an iOS device's media apps, such as Music, Spotify, and Podcast apps.

Here's Apple's definition of the service:

The Apple Media Service (AMS) is used with Bluetooth accessories that connect to iOS devices through Bluetooth low-energy links. It gives them a simple and convenient way to control media apps and access information about the media states of the connected iOS devices.

AMS lets devices control the media player with remote commands for many common controls, such as:

  • play/pause
  • next track
  • previous track
  • volume up/down
  • repeat mode

AMS also can send information from the media player to the remote device when requested, including:

  • track title
  • track artist
  • track album
  • repeat mode
  • track duration
  • media player name (e.g., Spotify, Music, Podcast)

In this example, the remote device requests attributes values for Track Title, Track Artist, and Track Album.

The media player receives these requests and responds with Tall Bird, Bartlebeats, and Frequency.

For a full list of Remote Commands and Entity Attributes, check the Apple Media Service Reference here.

In order to make it simple to interface with your iOS device from an Adafruit Bluefruit nRF52840 board, we've created a BLE Apple Media library for CircuitPython. This library takes care of the nitty gritty details, and lets you get on with the fun part of creating a device to show what song is playing and to control the player remotely!

In code, you'll import the Apple Media Service library. Once the devices are connected, the service is instantiated with ams = connection[AppleMediaService] and you can then use simple commands in CircuitPython to control the media player, such as:

ams.toggle_play_pause()

ams.next_track()

ams.volume_up()

ams.like_track()

And, you can request media attribute info such as:

ams.title

ams.album

ams.artist

ams.playing

ams.paused

Full Command and Attribute Lists

You may decide you want to do something different with your device, or display different information. Below you'll find the commands that we can send and info we can request using  the Adafruit_CircuitPython_BLE_Apple_Media library.

NOTE: Not all media apps support every command or info request.

Commands

  • play -- Plays the current track. Does nothing if already playing
  • pause -- Pauses the current track. Does nothing if already paused
  • toggle_play_pause -- Plays the current track if it is paused. Otherwise it pauses the track
  • next_track -- Stops playing the current track and plays the next one
  • previous_track -- Stops playing the current track and plays the previous track
  • volume_up -- Increases the playback volume
  • volume_down -- Decreases the playback volume
  • advance_repeat_mode -- Advances the repeat mode. Modes are: Off, One and All
  • advance_shuffle_mode -- Advances the shuffle mode. Modes are: Off, One and All
  • skip_forward -- Skips forwards in the current track
  • skip_backward -- Skips backwards in the current track
  • like_track -- Likes the current track
  • dislike_track -- Dislikes the current track
  • bookmark_track -- Bookmarks the current track

Info

  • player_name -- Name of the media player app
  • paused -- True when playback is paused. False otherwise
  • playing -- True when playback is playing
  • rewinding -- True when playback is rewinding
  • fast_forwarding -- True when playback is fast-forwarding
  • playback_rate -- Playback rate as a decimal of normal speed
  • elapsed_time -- Time elapsed in the current track. Not updated as the track plays. Use (amount of time since read elapsed time) * playback_rate to estimate the current elapsed_time
  • volume -- Current volume
  • queue_index -- Current track's index in the queue
  • queue_length -- Count of tracks in the queue
  • shuffle_mode -- Current shuffle mode as an integer. 0 = Off, 1 = One, 2 = All
  • repeat_mode -- Current repeat mode as an integer. 0 = Off, 1 = One, 2 = All
  • artist -- Current track's artist name
  • album -- Current track's album name
  • title -- Current track's title (a.k.a., song name)
  • duration -- Current track's duration as a string

 

This guide was first published on Jan 26, 2020. It was last updated on Jan 26, 2020.

This page (Apple Media Service) was last updated on Oct 15, 2021.

Text editor powered by tinymce.