google-music-utils

A set of utility functionality for google-music and related projects.

Constants

CHARACTER_REPLACEMENTS

Mapping of invalid filepath characters with appropriate replacements.

FIELD_MAP

Mapping of field name aliases.

TEMPLATE_PATTERNS

Mapping of template patterns to their audio-metadata field name.

Functions

Compare

find_existing_items(src, dst, *, fields=None, field_map=None, normalize_values=False, normalize_func=<function normalize_value>)[source]

Find items from an item collection that are in another item collection.

Parameters
  • src (list) – A list of item dicts or filepaths.

  • dst (list) – A list of item dicts or filepaths.

  • fields (list, Optional) – A list of fields used to compare item dicts.

  • field_map (Mapping, Optional) – A mapping field name aliases. Default: FIELD_MAP

  • normalize_values (bool, Optional) – Normalize metadata values to remove common differences between sources. Default: False

  • normalize_func (callable, Optional) – Function to apply to metadata values if normalize_values is True. Default: normalize_value

Yields

dict – The next item from src collection in dst collection.

find_missing_items(src, dst, *, fields=None, field_map=None, normalize_values=False, normalize_func=<function normalize_value>)[source]

Find items from an item collection that are not in another item collection.

Parameters
  • src (list) – A list of item dicts or filepaths.

  • dst (list) – A list of item dicts or filepaths.

  • fields (list, Optional) – A list of fields used to compare item dicts.

  • field_map (Mapping, Optional) – A mapping field name aliases. Default: FIELD_MAP

  • normalize_values (bool, Optional) – Normalize metadata values to remove common differences between sources. Default: False

  • normalize_func (callable, Optional) – Function to apply to metadata values if normalize_values is True. Default: normalize_value

Yields

dict – The next item from src collection not in dst collection.

Filter

exclude_items(items, *, any_all=<built-in function any>, ignore_case=False, normalize_values=False, **kwargs)[source]

Exclude items by matching metadata.

Note

Metadata values are lowercased when normalized_values is True, so ignore_case is automatically set to True.

Parameters
  • items (list) – A list of item dicts or filepaths.

  • any_all (callable, Optional) – A callable to determine if any or all filters must match to exclude items. Expected values any (default) or all.

  • ignore_case (bool, Optional) – Perform case-insensitive matching. Default: False

  • normalize_values (bool, Optional) – Normalize metadata values to remove common differences between sources. Default: False

  • kwargs (list, Optional) – Lists of values to match the given metadata field.

Yields

dict – The next item to be included.

Example

>>> from google_music_utils import exclude_items
>>> list(exclude_items(song_list, any_all=all, ignore_case=True, normalize_values=True, artist=['Beck'], album=['Golden Feelings']))
include_items(items, *, any_all=<built-in function any>, ignore_case=False, normalize_values=False, **kwargs)[source]

Include items by matching metadata.

Note

Metadata values are lowercased when normalized_values is True, so ignore_case is automatically set to True.

Parameters
  • items (list) – A list of item dicts or filepaths.

  • any_all (callable, Optional) – A callable to determine if any or all filters must match to include items. Expected values any (default) or all.

  • ignore_case (bool, Optional) – Perform case-insensitive matching. Default: False

  • normalize_values (bool, Optional) – Normalize metadata values to remove common differences between sources. Default: False

  • kwargs (list, Optional) – Lists of values to match the given metadata field.

Yields

dict – The next item to be included.

Example

>>> from google_music_utils import exclude_items
>>> list(include_items(song_list, any_all=all, ignore_case=True, normalize_values=True, artist=['Beck'], album=['Odelay']))

Metadata

gm_timestamp()[source]

Generate a timestamp in microseconds.

from_gm_timestamp(timestamp)[source]

Convert timestamp in microseconds to timestamp in seconds.

to_gm_timestamp(timestamp)[source]

Convert timestamp in seconds to timestamp in microseconds.

is_album_id(item_id)[source]

Validate if ID is in the format of a Google Music album ID.

is_artist_id(item_id)[source]

Validate if ID is in the format of a Google Music artist ID.

is_podcast_episode_id(item_id)[source]

Validate if ID is in the format of a Google Music podcast episode ID.

is_podcast_series_id(item_id)[source]

Validate if ID is in the format of a Google Music series ID.

is_store_song_id(item_id)[source]

Validate if ID is in the format of a Google Music store song ID.

is_uuid(item_id)[source]

Validate if ID is in the format of a UUID (used for library song IDs).

Misc

suggest_filename(metadata)[source]

Generate a filename like Google for a song based on metadata.

Parameters

metadata (Mapping) – A metadata dict.

Returns

A filename string without an extension.

Return type

str

template_to_filepath(template, metadata, template_patterns=None)[source]

Create directory structure and file name based on metadata template.

Note:

A template meant to be a base directory for suggested names should have a trailing slash or backslash.

Parameters
  • template (str or PathLike) – A filepath which can include template patterns as defined by :param template_patterns:.

  • metadata (Mapping) – A metadata dict.

  • template_patterns (Mapping) – A dict of pattern: field pairs used to replace patterns with metadata field values. Default: TEMPLATE_PATTERNS

Returns

A filepath.

Return type

Path

Utils

normalize_value(value)[source]

Normalize metadata value to improve match accuracy.