MobileClient
— Mobile API client¶
-
class
MobileClient
(username=None, device_id=None, *, locale='en_US', session=None, token=None, token_handler=<class 'google_music.token_handlers.FileTokenHandler'>, token_handler_kwargs=None)[source]¶ API wrapper class to access Google Music mobile client functionality.
>>> from google_music import MobileClient >>> mc = MobileClient('username')
Note
Streaming requires a
device_id
from a valid, linked mobile device. TheMobileClient
instance’sdevice_id
can be changed after instantiation, or a differentdevice_id
provided tostream
orstream_url
.- Parameters
username (str, Optional) – Your Google Music username. Used to store OAuth tokens for multiple accounts separately.
device_id (str, Optional) – A mobile device ID. Default: MAC address is used.
locale (str, Optional) – ICU locale used to localize some responses. This must be a locale supported by Android. Default:
'en_US'
.session (
GoogleMusicSession
, Optional) – A session compatible withGoogleMusicSession
.token (dict, Optional) – An OAuth token compatible with
oauthlib
.token_handler (
TokenHandler
, Optional) – A token handler class compatible withTokenHandler
for dumping and loading the OAuth token.token_handler_kwargs (dict, Optional) – Keyword arguments to pass to the
token_handler
class. These become attributes on the class instance.
Properties¶
-
MobileClient.
device_id
¶ The mobile device ID of the
MobileClient
instance.
-
MobileClient.
is_subscribed
¶ The subscription status of the account linked to the
MobileClient
instance.
-
MobileClient.
locale
¶ The locale of the
MobileClient
instance.Can be changed after instantiation.
ICU locale used to localize some responses. This must be a locale supported by Android.
-
MobileClient.
tier
¶ The subscription tier of the
MobileClient
instance.Can be changed after instantiation.
aa
if subscribed,fr
if not.
Meta¶
-
MobileClient.
device_set
(device)[source]¶ Set device used by
MobileClient
instance.
Information¶
-
MobileClient.
album
(album_id, *, include_description=True, include_songs=True)[source]¶ Get information about an album.
- Parameters
- Returns
Album information.
- Return type
-
MobileClient.
artist
(artist_id, *, include_albums=True, num_related_artists=5, num_top_tracks=5)[source]¶ Get information about an artist.
- Parameters
artist_id (str) – An artist ID. Artist IDs start with an ‘A’.
include_albums (bool, Optional) – Include albums by the artist in returned dict. Default:
True
.num_related_artists (int, Optional) – Include up to given number of related artists in returned dict. Default:
5
.num_top_tracks (int, Optional) – Include up to given number of top tracks in returned dict. Default:
5
.
- Returns
Artist information.
- Return type
-
MobileClient.
playlist
(playlist_id, *, include_songs=False)[source]¶ Get information about a playlist.
-
MobileClient.
playlist_song
(playlist_song_id)[source]¶ Get information about a playlist song.
Note
This returns the playlist entry information only. For full song metadata, use
song
with the'trackId'
field.
-
MobileClient.
podcast
(podcast_series_id, *, max_episodes=50)[source]¶ Get information about a podcast series.
-
MobileClient.
station
(station_id, *, num_songs=25, recently_played=None)[source]¶ Get information about a station.
- Parameters
station_id (str) – A station ID. Use ‘IFL’ for I’m Feeling Lucky.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
25
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.
- Returns
Station information.
- Return type
Browse¶
-
MobileClient.
browse_podcasts
(podcast_genre_id='JZCpodcasttopchartall')[source]¶ Get the podcasts for a genre from the Podcasts browse tab.
- Parameters
podcast_genre_id (str, Optional) – A podcast genre ID as found in
browse_podcasts_genres
. Default:'JZCpodcasttopchartall'
.- Returns
Podcast dicts.
- Return type
-
MobileClient.
browse_podcasts_genres
()[source]¶ Get the genres from the Podcasts browse tab dropdown.
- Returns
Genre groups that contain sub groups.
- Return type
-
MobileClient.
browse_stations
(station_category_id)[source]¶ Get the stations for a category from Browse Stations.
- Parameters
station_category_id (str) – A station category ID as found with
browse_stations_categories
.- Returns
Station dicts.
- Return type
-
MobileClient.
browse_stations_categories
()[source]¶ Get the categories from Browse Stations.
- Returns
Station categories that can contain subcategories.
- Return type
Explore¶
-
MobileClient.
explore_tabs
(*, num_items=100, genre_id=None)[source]¶ Get a listing of explore tabs.
- Parameters
num_items (int, Optional) – Number of items per tab to return. Default:
100
genre_id (genre_id, Optional) – Genre ID from
explore_genres
to explore. Default:None
.
- Returns
Explore tabs content.
- Return type
Listen Now¶
-
MobileClient.
listen_now_dismissed_items
()[source]¶ Get a listing of items dismissed from Listen Now tab.
-
MobileClient.
listen_now_items
()[source]¶ Get a listing of Listen Now items.
Note
This does not include situations; use the
situations
method instead.- Returns
With
albums
andstations
keys of listen now items.- Return type
-
MobileClient.
situations
(*, tz_offset=None)[source]¶ Get a listing of situations.
- Parameters
tz_offset (int, Optional) – A timezone offset from UTC in seconds.
Playlists¶
-
MobileClient.
playlist
(playlist_id, *, include_songs=False)[source] Get information about a playlist.
-
MobileClient.
playlists_iter
(*, start_token=None, page_size=250)[source]¶ Get a paged iterator of library playlists.
-
MobileClient.
playlist_create
(name, description='', *, public=False, songs=None)[source]¶ Create a playlist.
- Parameters
- Returns
Playlist information.
- Return type
-
MobileClient.
playlist_delete
(playlist)[source]¶ Delete a playlist.
- Parameters
playlist (dict) – A playlist dict.
-
MobileClient.
playlist_edit
(playlist, *, name=None, description=None, public=None)[source]¶ Edit playlist(s).
-
MobileClient.
playlist_unsubscribe
(playlist)[source]¶ Unsubscribe from a public playlist.
- Parameters
playlist (dict) – A public playlist dict.
-
MobileClient.
playlist_song
(playlist_song_id)[source] Get information about a playlist song.
Note
This returns the playlist entry information only. For full song metadata, use
song
with the'trackId'
field.
-
MobileClient.
playlist_songs
(playlist)[source]¶ Get a listing of songs from a playlist.
- Paramters:
playlist (dict): A playlist dict.
- Returns
Playlist song dicts.
- Return type
-
MobileClient.
playlist_songs_add
(songs, playlist, *, after=None, before=None, index=None, position=None)[source]¶ Add songs to a playlist.
Note
Provide no optional arguments to add to end.
Provide playlist song dicts for
after
and/orbefore
.Provide a zero-based
index
.Provide a one-based
position
.
Songs are inserted at given index or position. It’s also possible to add to the end by using
len(songs)
for index orlen(songs) + 1
for position.- Parameters
playlist (dict) – A playlist dict.
after (dict, Optional) – A playlist song dict
songs
will follow.before (dict, Optional) – A playlist song dict
songs
will precede.index (int, Optional) – The zero-based index position to insert
songs
.position (int, Optional) – The one-based position to insert
songs
.
- Returns
Playlist dict including songs.
- Return type
-
MobileClient.
playlist_songs_move
(playlist_songs, *, after=None, before=None, index=None, position=None)[source]¶ Move songs in a playlist.
Note
Provide no optional arguments to move to end.
Provide playlist song dicts for
after
and/orbefore
.Provide a zero-based
index
.Provide a one-based
position
.
Songs are inserted at given index or position. It’s also possible to move to the end by using
len(songs)
for index orlen(songs) + 1
for position.- Parameters
playlist_songs (list) – A list of playlist song dicts.
after (dict, Optional) – A playlist song dict
songs
will follow.before (dict, Optional) – A playlist song dict
songs
will precede.index (int, Optional) – The zero-based index position to insert
songs
.position (int, Optional) – The one-based position to insert
songs
.
- Returns
Playlist dict including songs.
- Return type
-
MobileClient.
thumbs_up_songs
(*, library=True, store=True)[source]¶ Get a listing of ‘Thumbs Up’ songs.
Podcasts¶
-
MobileClient.
podcast
(podcast_series_id, *, max_episodes=50)[source] Get information about a podcast series.
-
MobileClient.
podcasts
(*, device_id=None)[source]¶ Get a listing of subsribed podcast series.
- Paramaters:
- device_id (str, Optional):
A mobile device ID. Default: Use
device_id
.
- Returns
Podcast series dict.
- Return type
-
MobileClient.
podcasts_iter
(*, device_id=None, page_size=250)[source]¶ Get a paged iterator of subscribed podcast series.
-
MobileClient.
podcast_episode
(podcast_episode_id)[source] Get information about a podcast_episode.
-
MobileClient.
podcast_episodes
(*, device_id=None)[source]¶ Get a listing of podcast episodes for all subscribed podcasts.
- Paramaters:
- device_id (str, Optional): A mobile device ID.
Default: Use
device_id
of theMobileClient
instance.
- Returns
Podcast episode dicts.
- Return type
-
MobileClient.
podcast_episodes_iter
(*, device_id=None, page_size=250)[source]¶ Get a paged iterator of podcast episode for all subscribed podcasts.
Search¶
-
MobileClient.
search
(query, *, max_results=100, **kwargs)[source]¶ Search Google Music and library for content.
- Parameters
query (str) – Search text.
max_results (int, Optional) – Maximum number of results per type per location to retrieve. I.e up to 100 Google and 100 library for a total of 200 for the default value. Google only accepts values up to 100. Default:
100
kwargs (bool, Optional) –
- Any of:
'albums'
'artists'
'genres'
'playlists'
'podcasts'
'situations'
'songs'
'stations'
'videos'
set to
True
will include that result type in the returned dict. Setting none of them will include all result types in the returned dict.
- Returns
- A dict of results separated into keys:
'albums'
'artists'
'genres'
'playlists'
`'podcasts'
'situations'
,'songs'
'stations'
'videos'
- Return type
Note
Free account search is restricted so may not contain hits for all result types.
-
MobileClient.
search_google
(query, *, max_results=100, **kwargs)[source]¶ Search Google Music for content.
- Parameters
query (str) – Search text.
max_results (int, Optional) – Maximum number of results per type to retrieve. Google only accepts values up to 100. Default:
100
kwargs (bool, Optional) –
- Any of:
'albums'
'artists'
'genres'
'playlists'
'podcasts'
'situations'
'songs'
'stations'
'videos'
set to
True
will include that result type in the returned dict. Setting none of them will include all result types in the returned dict.
- Returns
- A dict of results separated into keys:
albums
artists
genres
playlists
podcasts
situations
songs
stations
videos
- Return type
Note
Free account search is restricted so may not contain hits for all result types.
-
MobileClient.
search_library
(query, *, max_results=100, **kwargs)[source]¶ Search Google Music for content.
- Parameters
query (str) – Search text.
max_results (int, Optional) – Maximum number of results per type to retrieve. Default:
100
kwargs (bool, Optional) –
- Any of:
'playlists'
'podcasts'
'songs'
'stations'
set to
True
will include that result type in the returned dict. Setting none of them will include all result types in the returned dict.
- Returns
- A dict of results separated into keys:
'playlists'
'podcasts'
'songs'
'stations'
- Return type
Shuffle/Instant Mix¶
-
MobileClient.
shuffle_album
(album, *, num_songs=100, only_library=False, recently_played=None)[source]¶ Get a listing of album shuffle/mix songs.
- Parameters
album (dict) – An album dict.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
100
only_library (bool, Optional) – Only return content from library. Default: False
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.
- Returns
List of album shuffle/mix songs.
- Return type
-
MobileClient.
shuffle_artist
(artist, *, num_songs=100, only_library=False, recently_played=None, only_artist=False)[source]¶ Get a listing of artist shuffle/mix songs.
- Parameters
artist (dict) – An artist dict.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
100
only_library (bool, Optional) – Only return content from library. Default: False
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.only_artist (bool, Optional) – If
True
, only return songs from the artist, else return songs from artist and related artists. Default:False
- Returns
List of artist shuffle/mix songs.
- Return type
-
MobileClient.
shuffle_genre
(genre, *, num_songs=100, only_library=False, recently_played=None)[source]¶ Get a listing of genre shuffle/mix songs.
- Parameters
genre (dict) – A genre dict.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
100
only_library (bool, Optional) – Only return content from library. Default: False
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.
- Returns
List of genre shuffle/mix songs.
- Return type
-
MobileClient.
shuffle_song
(song, *, num_songs=100, only_library=False, recently_played=None)[source]¶ Get a listing of song shuffle/mix songs.
- Parameters
song (dict) – A song dict.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
100
only_library (bool, Optional) – Only return content from library. Default: False
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.
- Returns
List of artist shuffle/mix songs.
- Return type
Songs¶
-
MobileClient.
song
(song_id)[source] Get information about a song.
-
MobileClient.
songs_iter
(*, page_size=250)[source]¶ Get a paged iterator of library songs.
- Parameters
page_size (int, Optional) – The maximum number of results per returned page. Max allowed is
49995
. Default:250
- Yields
list – Song dicts.
-
MobileClient.
thumbs_up_songs
(*, library=True, store=True)[source] Get a listing of ‘Thumbs Up’ songs.
Stations¶
-
MobileClient.
situations
(*, tz_offset=None)[source] Get a listing of situations.
- Parameters
tz_offset (int, Optional) – A timezone offset from UTC in seconds.
-
MobileClient.
station
(station_id, *, num_songs=25, recently_played=None)[source] Get information about a station.
- Parameters
station_id (str) – A station ID. Use ‘IFL’ for I’m Feeling Lucky.
num_songs (int, Optional) – The maximum number of songs to return from the station. Default:
25
recently_played (list, Optional) – A list of dicts in the form of {‘id’: ‘’, ‘type’} where
id
is a song ID andtype
is 0 for a library song and 1 for a store song.
- Returns
Station information.
- Return type
-
MobileClient.
stations
(*, generated=True, library=True)[source]¶ Get a listing of library stations.
The listing can contain stations added to the library and generated from the library.
-
MobileClient.
stations_iter
(*, page_size=250)[source]¶ Get a paged iterator of library stations.
- Parameters
page_size (int, Optional) – The maximum number of results per returned page. Max allowed is
49995
. Default:250
- Yields
list – Station dicts.
-
MobileClient.
station_feed
(*, num_songs=25, num_stations=4)[source]¶ Generate stations.
Note
A Google Music subscription is required.
-
MobileClient.
station_songs
(station, *, num_songs=25, recently_played=None)[source]¶ Get a listing of songs from a station.
- Parameters
- Returns
Station song dicts.
- Return type
Stream¶
-
MobileClient.
stream
(item, *, device_id=None, quality='hi', session_token=None)[source]¶ Get MP3 stream of a podcast episode, library song, station_song, or store song.
Note
Streaming requires a
device_id
from a valid, linked mobile device.- Parameters
item (str) – A podcast episode, library song, station_song, or store song. A Google Music subscription is required to stream store songs.
device_id (str, Optional) – A mobile device ID. Default: Use
device_id
.quality (str, Optional) –
- Stream quality is one of:
'hi'
(320Kbps)'med'
(160Kbps)'low'
(128Kbps)
Default:
'hi'
.session_token (str, Optional) – Session token from a station dict required for unsubscribed users to stream a station song. station[‘sessionToken’] as returend by
station
only exists for free accounts.
- Returns
An MP3 file.
- Return type
-
MobileClient.
stream_url
(item, *, device_id=None, quality='hi', session_token=None)[source]¶ Get a URL to stream a podcast episode, library song, station_song, or store song.
Note
Streaming requires a
device_id
from a valid, linked mobile device.- Parameters
item (str) – A podcast episode, library song, station_song, or store song. A Google Music subscription is required to stream store songs.
device_id (str, Optional) – A mobile device ID. Default: Use
device_id
.quality (str, Optional) –
- Stream quality is one of:
'hi'
(320Kbps)'med'
(160Kbps)'low'
(128Kbps)
Default:
'hi'
.session_token (str) – Session token from a station dict required for unsubscribed users to stream a station song. station[‘sessionToken’] as returend by
station
only exists for free accounts.
- Returns
A URL to an MP3 file.
- Return type
Top Charts¶
-
MobileClient.
top_charts_for_genre
(genre_id)[source]¶ Get a listing of top charts for a top chart genre.
- Parameters
genre_id (str) – A top chart genre ID as found with
top_charts_genres
.