gmusicapi-wrapper Documentation

Transcription

1 gmusicapi-wrapper Documentation Release thebigmunch Nov 02, 2017

2

3 Contents 1 Mobile Client 3 2 Music Manager 7 3 Utils 11 Python Module Index 15 i

4 ii

5 A wrapper interface for gmusicapi providing extra functionality and conveniences. Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Mobile Client Mobile Client functionality. >>> from gmusicapi_wrapper import MobileClientWrapper class MobileClientWrapper(enable_logging=False) Wrap gmusicapi s Mobileclient client interface to provide extra functionality and conveniences. enable_logging (bool) Enable gmusicapi s debug_logging option. login(username=none, password=none, android_id=none) Authenticate the gmusicapi Mobileclient instance. username (Optional[str]) Your Google Music username. Will be prompted if not given. password (Optional[str]) Your Google Music password. Will be prompted if not given. android_id (Optional[str]) The 16 hex digits from an Android device ID. Default: Use gmusicapi.mobileclient.from_mac_address to create ID from computer s MAC address. Returns True on successful login or False on unsuccessful login. logout() Log out the gmusicapi Mobileclient instance. Returns True on success. is_authenticated Check the authentication status of the gmusicapi client instance. Returns True if authenticated, False if not. is_subscribed Check the subscription status of the gmusicapi client instance. 3

8 Returns True if subscribed, False if not. get_local_songs(filepaths, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false, exclude_patterns=none, max_depth=inf ) Load songs from local filepaths. filepaths (list or str) Filepath(s) to search for music files. include_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a exclude_patterns (list or str) Pattern(s) to exclude. Patterns are Python regex patterns. Filepaths are excluded if they match any of the exclude patterns. max_depth (int) The depth in the directory tree to walk. A depth of 0 limits the walk to the top directory. Default: No limit. Returns A list of local song filepaths matching criteria, a list of local song filepaths filtered out using filter criteria, and a list of local song filepaths excluded using exclusion criteria. get_google_songs(include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false) Create song list from user s Google Music library. include_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Mobileclient client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Mobileclient client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a Returns A list of Google Music song dicts matching criteria and a list of Google Music song dicts filtered out using filter criteria. get_local_playlists(filepaths, exclude_patterns=none, max_depth=inf ) Load playlists from local filepaths. filepaths (list or str) Filepath(s) to search for music files. 4 Chapter 1. Mobile Client

9 exclude_patterns (list or str) Pattern(s) to exclude. Patterns are Python regex patterns. Filepaths are excluded if they match any of the exclude patterns. max_depth (int) The depth in the directory tree to walk. A depth of 0 limits the walk to the top directory. Default: No limit. Returns A list of local playlist filepaths matching criteria and a list of local playlist filepaths excluded using exclusion criteria. get_local_playlist_songs(playlist, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false, exclude_patterns=none) Load songs from local playlist. playlist (str) An M3U(8) playlist filepath. include_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a exclude_patterns (list or str) Pattern(s) to exclude. Patterns are Python regex patterns. Filepaths are excluded if they match any of the exclude patterns. Returns A list of local playlist song filepaths matching criteria, a list of local playlist song filepaths filtered out using filter criteria, and a list of local playlist song filepaths excluded using exclusion criteria. get_google_playlist(playlist) Get playlist information of a user-generated Google Music playlist. playlist (str) Name or ID of Google Music playlist. Names are casesensitive. Google allows multiple playlists with the same name. If multiple playlists have the same name, the first one encountered is used. Returns The playlist dict as returned by Mobileclient.get_all_user_playlist_contents. Return type dict get_google_playlist_songs(playlist, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false) Create song list from a user-generated Google Music playlist. playlist (str) Name or ID of Google Music playlist. Names are case-sensitive. Google allows multiple playlists with the same name. If multiple playlists have the same name, the first one encountered is used. include_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values don t match any of the given patterns. 5

10 exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a Returns A list of Google Music song dicts in the playlist matching criteria and a list of Google Music song dicts in the playlist filtered out using filter criteria. 6 Chapter 1. Mobile Client

11 CHAPTER 2 Music Manager Music Manager functionality. >>> from gmusicapi_wrapper import MusicManagerWrapper class MusicManagerWrapper(enable_logging=False) Wrap gmusicapi s Musicmanager client interface to provide extra functionality and conveniences. enable_logging (bool) Enable gmusicapi s debug_logging option. login(oauth_filename= oauth, uploader_id=none) Authenticate the gmusicapi Musicmanager instance. oauth_filename (str) The filename of the oauth credentials file to use/create for login. Default: oauth uploader_id (str) A unique id as a MAC address (e.g. '00:11:22:33:AA:BB'). This should only be provided in cases where the default (host MAC address incremented by 1) won t work. Returns True on successful login, False on unsuccessful login. logout(revoke_oauth=false) Log out the gmusicapi Musicmanager instance. revoke_oauth (bool) If True, oauth credentials will be revoked and the corresponding oauth file will be deleted. Returns True on success. is_authenticated Check the authentication status of the gmusicapi client instance. Returns True if authenticated, False if not. get_local_songs(filepaths, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false, exclude_patterns=none, max_depth=inf ) Load songs from local filepaths. 7

12 filepaths (list or str) Filepath(s) to search for music files. include_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a exclude_patterns (list or str) Pattern(s) to exclude. Patterns are Python regex patterns. Filepaths are excluded if they match any of the exclude patterns. max_depth (int) The depth in the directory tree to walk. A depth of 0 limits the walk to the top directory. Default: No limit. Returns A list of local song filepaths matching criteria, a list of local song filepaths filtered out using filter criteria, and a list of local song filepaths excluded using exclusion criteria. get_google_songs(include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false, uploaded=true, purchased=true) Create song list from user s Google Music library. include_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a uploaded (bool) Include uploaded songs. Default: True. purchased (bool) Include purchased songs. Default: True. Returns A list of Google Music song dicts matching criteria and a list of Google Music song dicts filtered out using filter criteria. download(songs, template=none) Download Google Music songs. songs (list or dict) Google Music song dict(s). template (str) A filepath which can include template patterns. 8 Chapter 2. Music Manager

13 Returns A list of result dictionaries. [ {'result': 'downloaded', 'id': song_id, 'filepath': downloaded[song_id]}, # downloaded {'result': 'error', 'id': song_id, 'message': error[song_id]} # error ] upload(filepaths, enable_matching=false, transcode_quality= 320k, delete_on_success=false) Upload local songs to Google Music. filepaths (list or str) Filepath(s) to upload. enable_matching (bool) If True attempt to use scan and match. This requieres ffmpeg or avconv. transcode_quality (str or int) If int, pass to ffmpeg/avconv -q:a for libmp3lame VBR quality < If string, pass to ffmpeg/avconv -b:a for libmp3lame CBR quality < Default: 320k delete_on_success (bool) Delete successfully uploaded local files. False Returns A list of result dictionaries. Default: [ {'result': 'uploaded', 'filepath': <filepath>, 'id': <song_id>}, # uploaded {'result': 'matched', 'filepath': <filepath>, 'id': <song_id>}, # matched {'result': 'error', 'filepath': <filepath>, 'message': <error_ message>}, # error {'result': 'not_uploaded', 'filepath': <filepath>, 'id': <song_ id>, 'message': <reason_message>}, # not_uploaded ALREADY_EXISTS {'result': 'not_uploaded', 'filepath': <filepath>, 'message': <reason_message>} # not_uploaded ] 9

14 10 Chapter 2. Music Manager

15 CHAPTER 3 Utils Utility functions for gmusicapi_wrapper. >>> import gmusicapi_wrapper.utils as gmw_utils >>> from gmusicapi_wrapper.utils import... convert_cygwin_path(path) Convert Unix path from Cygwin to Windows path. compare_song_collections(src_songs, dst_songs) Compare two song collections to find missing songs. src_songs (list) Google Music song dicts or filepaths of local songs. dest_songs (list) Google Music song dicts or filepaths of local songs. Returns A list of Google Music song dicts or local song filepaths from source missing in destination. get_supported_filepaths(filepaths, supported_extensions, max_depth=inf ) Get filepaths with supported extensions from given filepaths. filepaths (list or str) Filepath(s) to check. supported_extensions (tuple or str) Supported file extensions or a single file extension. max_depth (int) The depth in the directory tree to walk. A depth of 0 limits the walk to the top directory. Default: No limit. Returns A list of supported filepaths. exclude_filepaths(filepaths, exclude_patterns=none) Exclude file paths based on regex patterns. filepaths (list or str) Filepath(s) to check. 11

16 exclude_patterns (list) Python regex patterns to check filepaths against. Returns A list of filepaths to include and a list of filepaths to exclude. filter_google_songs(songs, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false) Match a Google Music song dict against a set of metadata filters. Returns songs (list) Google Music song dicts to filter. include_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid Google Music metadata field available to the Musicmanager client. Patterns are Python regex patterns. Google Music songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a A list of Google Music song dicts matching criteria and a list of Google Music song dicts filtered out using filter criteria. (matched, filtered) filter_local_songs(filepaths, include_filters=none, exclude_filters=none, all_includes=false, all_excludes=false) Match a local file against a set of metadata filters. Returns filepaths (list) Filepaths to filter. include_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values don t match any of the given patterns. exclude_filters (list) A list of (field, pattern) tuples. Fields are any valid mutagen metadata fields. Patterns are Python regex patterns. Local songs are filtered out if the given metadata field values match any of the given patterns. all_includes (bool) If True, all include_filters criteria must match to include a all_excludes (bool) If True, all exclude_filters criteria must match to exclude a A list of local song filepaths matching criteria and a list of local song filepaths filtered out using filter criteria. Invalid music files are also filtered out. (matched, filtered) 12 Chapter 3. Utils

17 get_suggested_filename(metadata) Generate a filename for a song based on metadata. metadata (dict) A metadata dict. Returns A filename. template_to_filepath(template, metadata, template_patterns=none) Create directory structure and file name based on metadata template. template (str) A filepath which can include template patterns as defined by :param template_patterns:. metadata (dict) A metadata dict. template_patterns (dict) A dict of pattern: field pairs used to replace patterns with metadata field values. Default: :const TEMPLATE_PATTERNS: Returns A filepath. walk_depth(path, max_depth=inf ) Walk a directory tree with configurable depth. path (str) A directory path to walk. max_depth (int) The depth in the directory tree to walk. A depth of 0 limits the walk to the top directory. Default: No limit. 13

18 14 Chapter 3. Utils

19 Python Module Index g gmusicapi_wrapper.mobileclient, 3 gmusicapi_wrapper.musicmanager, 7 gmusicapi_wrapper.utils, 11 15

20 16 Python Module Index

21 Index C compare_song_collections() (in module gmusicapi_wrapper.utils), 11 convert_cygwin_path() (in module gmusicapi_wrapper.utils), 11 D download() (MusicManagerWrapper method), 8 E exclude_filepaths() (in module gmusicapi_wrapper.utils), 11 F filter_google_songs() (in module gmusicapi_wrapper.utils), 12 filter_local_songs() (in module gmusicapi_wrapper.utils), 12 G get_google_playlist() (MobileClientWrapper method), 5 get_google_playlist_songs() (MobileClientWrapper method), 5 get_google_songs() (MobileClientWrapper method), 4 get_google_songs() (MusicManagerWrapper method), 8 get_local_playlist_songs() (MobileClientWrapper method), 5 get_local_playlists() (MobileClientWrapper method), 4 get_local_songs() (MobileClientWrapper method), 4 get_local_songs() (MusicManagerWrapper method), 7 get_suggested_filename() (in module gmusicapi_wrapper.utils), 12 get_supported_filepaths() (in module gmusicapi_wrapper.utils), 11 gmusicapi_wrapper.mobileclient (module), 3 gmusicapi_wrapper.musicmanager (module), 7 gmusicapi_wrapper.utils (module), 11 I is_authenticated (MobileClientWrapper attribute), 3 is_authenticated (MusicManagerWrapper attribute), 7 is_subscribed (MobileClientWrapper attribute), 3 L login() (MobileClientWrapper method), 3 login() (MusicManagerWrapper method), 7 logout() (MobileClientWrapper method), 3 logout() (MusicManagerWrapper method), 7 M MobileClientWrapper (class in gmusicapi_wrapper.mobileclient), 3 MusicManagerWrapper (class in gmusicapi_wrapper.musicmanager), 7 T template_to_filepath() (in module gmusicapi_wrapper.utils), 13 U upload() (MusicManagerWrapper method), 9 W walk_depth() (in module gmusicapi_wrapper.utils), 13 17