music

Access to the media library

Use the music module to access the Music library of the user and to play items.

Example:

import music
music.set_queue_with_items(music.pick_music())
music.play()

Playing music

music.set_queue_with_items(items: List[music.MediaItem])

Sets a music player’s playback queue using a media item collection.

Parameters:items – An array of MediaItem that you want as the playback queue.
music.set_queue_with_store_ids(ids: List[str])

Sets a music player’s playback queue using with media items identified by the store identifiers.

Parameters:ids – An array of store identifiers associated with the media items to be added to the queue.
music.play()

Initiates playback of the current item.

music.stop()

Ends playback of the current item.

music.restart()

Restarts playback at the beginning of the currently playing media item.

music.next()

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.

music.previous()

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.

music.set_shuffle_mode(mode: int)

Sets the shuffle mode of the music player.

Parameters:mode – The shuffle mode to set. See Shuffle Mode for possible values.
music.set_repeat_mode(mode: int)

Sets the repeat mode of the music player.

Parameters:mode – The repeat mode to set. See Repeat Mode for possible values.
music.playback_state() → int

The current playback state of the music player.

Return type:Playback State

Now playing item

music.now_playing_item() → music.MediaItem

The currently-playing media item, or the media item, within a queue, that you have designated to begin playback with.

Return type:MediaItem
music.index_of_now_playing_item() → int

The index of the now playing item in the current playback queue.

Return type:int

Picking music

music.pick_music() → List[music.MediaItem]

Picks music with a UI.

Returns a list of selected items.

Return type:List[MediaItem]

Classes

class music.MediaItem(item: MPMediaItem)

A collection of properties that represents a single item contained in the media library.

album_artist

The primary performing artist for an album as a whole.

Return type:str
album_artist_persistent_id

The persistent identifier for the primary performing artist for an album as a whole.

Return type:str
album_persistent_id

The persistent identifier for an album.

Return type:str
album_title

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)”.

Return type:str
album_track_count

The number of tracks in the album that contains the media item.

Return type:int
artist

The performing artist(s) for a media item—which may vary from the primary artist for the album that a media item belongs to.

Return type:str
artist_persistent_id

The persistent identifier for an artist.

Return type:int
artwork

The artwork image for the media item.

Return type:PIL.Image
beats_per_minute

The number of musical beats per minute for the media item.

Return type:int
bookmark_time

The user’s place in the media item the most recent time it was played.

Return type:float
comments

Textual information about the media item.

Return type:str
composer

The musical composer for the media item.

Return type:str
composer_persistent_id

The persistent identifier for a composer.

Return type:str
date_added

The date the item was added to the library.

Return type:str
disc_count

The number of discs in the album that contains the media item.

Return type:int
disc_number

The disc number of the media item, for a media item that is part of a multi-disc album.

Return type:int
genre

The musical or film genre of the media item.

Return type:str
genre_persistent_id

The persistent identifier for a genre.

Return type:str
has_protected_asset

A Boolean indicating whether the media item has a protected asset.

Return type:bool
is_cloud_item

A Boolean value indicating whether the media item is an iCloud Music Library item.

Return type:bool
is_compilation

A Boolean value indicating whether the media item is part of a compilation.

Return type:bool
is_explicit_item

A Boolean value that indicates whether the item has explicit (adult) lyrics or language.

Return type:bool
last_played_date

The date a media item was last played.

Return type:str
lyrics

The lyrics for the media item.

Return type:str
persistent_id

The persistent identifier for the media item.

Return type:str
play_count

The number of times the user has played the media item.

Return type:int
playback_duration

The playback duration of the media item.

Return type:float
playback_store_id

The non-library identifier for a media item.

Return type:str
podcast_persistent_id

The persistent identifier for an audio podcast.

Return type:str
podcast_title

The title of a podcast, such as “This Martian Drudgery”, as opposed to the title of an individual episode of a podcast such as “Episode 12: Another Cold Day At The Pole”.

Return type:str
rating

The user-specified rating of the object in the range [0…5], where a value of 5 indicates the most favorable rating.

Return type:int
release_date

The date on which the media item was first publicly released.

Return type:str
skip_count

The number of times the user has skipped playing the item.

Return type:int
title

The title (or name) of the media item.

Return type:str
user_grouping

Grouping information for the media item.

Return type:str
class music.MediaQuery(query: MPMediaQuery)

A query that specifies a set of media items from the device’s media library by way of a filter and a grouping type.

classmethod albums() → music.MediaQuery

Creates a media query that matches music items and that groups and sorts collections by album name.

Return type:MediaQuery
classmethod artists() → music.MediaQuery

Creates a media query that matches music items and that groups and sorts collections by artist name.

Return type:MediaQuery
classmethod audiobook() → music.MediaQuery

Creates a media query that matches audio book items and that groups and sorts collections by audio book name.

Return type:MediaQuery
classmethod compilations() → music.MediaQuery

Creates a media query that matches compilation items and that groups and sorts collections by album name.

Return type:MediaQuery
classmethod composers() → music.MediaQuery

Creates a media query that matches all media items and that groups and sorts collections by composer name.

Return type:MediaQuery
classmethod genres() → music.MediaQuery

Creates a media query that matches all media items and that groups and sorts collections by genre name.

Return type:MediaQuery
items

An array of media items that match the media query’s predicate.

Return type:List[MediaItem]
classmethod playlists() → music.MediaQuery

Creates a media query that matches the entire library and that groups and sorts collections by playlist name.

Return type:MediaQuery
classmethod podcasts() → music.MediaQuery

Creates a media query that matches podcast items and that groups and sorts collections by podcast name.

Return type:MediaQuery
classmethod songs() → music.MediaQuery

Creates a media query that matches music items and that groups and sorts collections by song name.

Return type:MediaQuery

Objective-C classes

music.MPMusicPlayerController = 'MPMusicPlayerController'

The ‘MPMusicPlayerController’ class from the ‘MediaPlayer’ framework.

music.MPMediaItem = 'MPMediaItem'

The ‘MPMediaItem’ class from the ‘MediaPlayer’ framework.

music.MPMediaItemCollection = 'MPMediaItemCollection'

The ‘MPMediaItemCollection’ class from the ‘MediaPlayer’ framework.

music.MPMediaQuery = 'MPMediaQuery'

The ‘MPMusicMPMediaQueryPlayerController’ class from the ‘MediaPlayer’ framework.

Constants

Repeat mode

music.REPEAT_MODE_DEFAULT = 0

The user’s preferred repeat mode.

music.REPEAT_MODE_NONE = 1

The music player will not repeat the current song or playlist.

music.REPEAT_MODE_ONE = 2

The music player will repeat the current song.

music.REPEAT_MODE_ALL = 3

The music player will repeat the current playlist.

Shuffle mode

music.SHUFFLE_MODE_DEFAULT = 0

The user’s preferred shuffle mode.

music.SHUFFLE_MODE_OFF = 1

The playlist is not shuffled.

music.SHUFFLE_MODE_SONGS = 2

The playlist is shuffled by song.

music.SHUFFLE_MODE_ALBUMS = 3

The playlist is shuffled by album.

Playback state

music.PLAYBACK_STATE_STOPPED = 0

The music player is stopped.

music.PLAYBACK_STATE_PLAYING = 1

The music player is playing.

music.PLAYBACK_STATE_PAUSED = 2

The music player is paused.

music.PLAYBACK_STATE_INTERRUPTED = 3

The music player has been interrupted, such as by an incoming phone call.

music.PLAYBACK_STATE_SEEKING_FORWARD = 4

The music player is seeking forward.

music.PLAYBACK_STATE_SEEKING_BACKWARD = 5

The music player is seeking backward.