Webclient Interface

class gmusicapi.clients.Webclient(debug_logging=True, validate=True, verify_ssl=True)

Allows library management and streaming by posing as the music.google.com webclient.

Uploading is not supported by this client (use the Musicmanager to upload).

Any methods in this class that are duplicated by the Mobileclient should be considered deprecated. The following methods are not deprecated:

Setup and login

Webclient.__init__(debug_logging=True, validate=True, verify_ssl=True)
Parameters:
  • debug_logging

    each Client has a logger member. The logger is named gmusicapi.<client class><client number> and will propogate to the gmusicapi root logger.

    If this param is True, handlers will be configured to send this client’s debug log output to disk, with warnings and above printed to stderr. Appdirs user_log_dir is used by default. Users can run:

    from gmusicapi.utils import utils
    print utils.log_filepath
    

    to see the exact location on their system.

    If False, no handlers will be configured; users must create their own handlers.

    Completely ignoring logging is dangerous and not recommended. The Google Music protocol can change at any time; if something were to go wrong, the logs would be necessary for recovery.

  • validate

    if False, do not validate server responses against known schemas. This helps to catch protocol changes, but requires significant cpu work.

    This arg is stored as self.validate and can be safely modified at runtime.

  • verify_ssl – if False, exceptions will not be raised if there are problems verifying SSL certificates. Be wary of using this option; it’s almost always better to fix the machine’s SSL configuration than to ignore errors.
Webclient.login(email, password)

Authenticates the webclient. Returns True on success, False on failure.

Parameters:
  • email – eg 'test@gmail.com' or just 'test'.
  • password – password or app-specific password for 2-factor users. This is not stored locally, and is sent securely over SSL.

Users of two-factor authentication will need to set an application-specific password to log in.

Webclient.logout()

Forgets local authentication in this Api instance. Returns True on success.

Getting songs and playlists

Webclient.get_all_songs(incremental=False)

Returns a list of song dictionaries.

Parameters:incremental – if True, return a generator that yields lists of at most 2500 song dictionaries as they are retrieved from the server. This can be useful for presenting a loading bar to a user.
Webclient.get_all_playlist_ids(auto=True, user=True)

Returns a dictionary that maps playlist types to dictionaries.

Parameters:
  • auto

    create an 'auto' subdictionary entry. Currently, this will just map to {}; support for ‘Shared with me’ and ‘Google Play recommends’ is on the way ( #102).

    Other auto playlists are not stored on the server, but calculated by the client. See this gist for sample code for ‘Thumbs Up’, ‘Last Added’, and ‘Free and Purchased’.

  • user – create a user 'user' subdictionary entry for user-created playlists. This includes anything that appears on the left side ‘Playlists’ bar (notably, saved instant mixes).

User playlist names will be unicode strings.

Google Music allows multiple user playlists with the same name, so the 'user' dictionary will map onto lists of ids. Here’s an example response:

{
    'auto':{},

    'user':{
        u'Some Song Mix':[
            u'14814747-efbf-4500-93a1-53291e7a5919'
        ],

        u'Two playlists have this name':[
            u'c89078a6-0c35-4f53-88fe-21afdc51a414',
            u'86c69009-ea5b-4474-bd2e-c0fe34ff5484'
        ]
    }
}

There is currently no support for retrieving automatically-created instant mixes (see issue #67).

Webclient.get_playlist_songs(playlist_id)

Returns a list of song dictionaries, which include playlistEntryId keys for the given playlist.

Parameters:playlist_id – id of the playlist to load.

This will return [] if the playlist id does not exist.

Song downloading and streaming

Webclient.get_song_download_info(song_id)

Returns a tuple: ('<url>', <download count>).

Parameters:song_id – a single song id.

url will be None if the download limit is exceeded.

GM allows 2 downloads per song. The download count may not always be accurate, and the 2 download limit seems to be loosely enforced.

This call alone does not count towards a download - the count is incremented when url is retrieved.

Webclient.get_stream_audio(song_id, use_range_header=None)

Returns a bytestring containing mp3 audio for this song.

Parameters:
  • song_id – a single song id
  • use_range_header

    in some cases, an HTTP range header can be used to save some bandwidth. However, there’s no guarantee that the server will respect it, meaning that the client may get back an unexpected response when using it.

    There are three possible values for this argument:
    • None: (default) send header; fix response locally on problems
    • True: send header; raise IOError on problems
    • False: do not send header
Webclient.get_stream_urls(song_id)

Returns a list of urls that point to a streamable version of this song.

If you just need the audio and are ok with gmusicapi doing the download, consider using get_stream_audio() instead. This abstracts away the differences between different kinds of tracks:

  • normal tracks return a single url
  • All Access tracks return multiple urls, which must be combined
Parameters:song_id – a single song id.

While acquiring the urls requires authentication, retreiving the contents does not.

However, there are limitations on how the stream urls can be used:

  • the urls expire after a minute
  • only one IP can be streaming music at once. Other attempts will get an http 403 with X-Rejected-Reason: ANOTHER_STREAM_BEING_PLAYED.

This is only intended for streaming. The streamed audio does not contain metadata. Use get_song_download_info() or Musicmanager.download_song to download files with metadata.

Webclient.report_incorrect_match(song_ids)

Equivalent to the ‘Fix Incorrect Match’ button, this requests re-uploading of songs. Returns the song_ids provided.

Parameters:song_ids – a list of song ids to report, or a single song id.

Note that if you uploaded a song through gmusicapi, it won’t be reuploaded automatically - this currently only works for songs uploaded with the Music Manager. See issue #89.

This should only be used on matched tracks (song['type'] == 6).

Song manipulation

Webclient.change_song_metadata(songs)

Changes the metadata for some song dictionaries. Returns a list of the song ids changed.

Parameters:songs – a list of song dictionaries, or a single song dictionary.

Generally, stick to these metadata keys:

  • rating: set to 0 (no thumb), 1 (down thumb), or 5 (up thumb)
  • name: use this instead of title
  • album
  • albumArtist
  • artist
  • composer
  • disc
  • genre
  • playCount
  • totalDiscs
  • totalTracks
  • track
  • year
Webclient.upload_album_art(song_ids, image_filepath)

Uploads an image and sets it as the album art for songs.

Parameters:
  • song_ids – a list of song ids, or a single song id.
  • image_filepath – filepath of the art to use. jpg and png are known to work.

This function will always upload the provided image, even if it’s already uploaded. If the art is already uploaded and set for another song, copy over the value of the 'albumArtUrl' key using change_song_metadata() instead.

Webclient.delete_songs(song_ids)

Deletes songs from the entire library. Returns a list of deleted song ids.

Parameters:song_ids – a list of song ids, or a single song id.

Playlist content manipulation

Webclient.add_songs_to_playlist(playlist_id, song_ids)

Appends songs to a playlist. Returns a list of (song id, playlistEntryId) tuples that were added.

Parameters:
  • playlist_id – id of the playlist to add to.
  • song_ids – a list of song ids, or a single song id.
Webclient.remove_songs_from_playlist(playlist_id, sids_to_match)

Removes all copies of the given song ids from a playlist. Returns a list of removed (sid, eid) pairs.

Parameters:
  • playlist_id – id of the playlist to remove songs from.
  • sids_to_match – a list of song ids to match, or a single song id.

This does not always the inverse of a call to add_songs_to_playlist(), since multiple copies of the same song are removed.

Other

Webclient.get_registered_devices()

Returns a list of dictionaries representing devices associated with the account.

Performing the Musicmanager OAuth flow will register a device of type 'DESKTOP_APP'.

Installing the Android Google Music app and logging into it will register a device of type 'PHONE', which is required for streaming with the Mobileclient.

Here is an example response:

[
  {
    u'date': 1367470393588,           # utc-millisecond
    u'id':   u'AA:BB:CC:11:22:33',
    u'name': u'my-hostname',
    u'type': u'DESKTOP_APP'
   },
   {
    u'carrier':      u'Google',
    u'date':         1344808742774,
    u'id':           u'0x00112233aabbccdd',
    u'manufacturer': u'Asus',
    u'model':        u'Nexus 7',
    u'name':         u'',
    u'type':         u'PHONE',
   }
]