audiorename package¶

Module contents¶

Rename audio files from metadata tags.

audiorename.execute(*argv: str)[source]¶

Main function

Parameters: argv (list) – The command line arguments specified as a list: e. g ['--dry-run', '.']

Submodules¶

audiorename.args module¶

Create the command line interface using the package “argparse”.

class audiorename.args.ArgsDefault(**kwargs: Any)[source]¶

Bases: object

To document the return value of the audiorename.args.parse_args(). It can also be used to mock the args object for testing purposes.

audiorename.args.description() → str[source]¶: Build the description string.

audiorename.args.fields: Dict[str, FieldDoc] = {'ar_classical_album': {'category': 'common', 'description': 'The field “work” without the movement suffix. For example: “Horn Concerto: I. Allegro” -> “Horn Concerto”', 'examples': ['Horn Concerto', 'Die Meistersinger von Nürnberg']}, 'ar_classical_performer': {'category': 'common', 'data_type': 'str', 'description': '“ar_performer_short” or “albumartist” without the composer prefix: “Beethoven; Karajan, Mutter” -> “Karajan, Mutter”', 'examples': ['Karajan, Mutter', 'Karajan, StaDre']}, 'ar_classical_title': {'category': 'common', 'data_type': 'str', 'description': 'The movement title without the parent work prefix. For example “Horn Concerto: I. Allegro” -> “I. Allegro”', 'examples': ['I. Allegro', 'Akt III, Szene V. "Morgendlich leuchtend im rosigen Schein" (Walther, Volk, Meister, Sachs, Pogner, Eva)']}, 'ar_classical_track': {'category': 'common', 'data_type': 'str', 'description': 'If the title contains Roman numbers, then these are converted to arabic numbers with leading zeros. If no Roman numbers could be found, then the field “ar_combined_disctrack” is used.', 'examples': ['01', '4-08']}, 'ar_combined_album': {'category': 'common', 'description': '“album” without ” (Disc X)”.', 'examples': ['Headlines and Deadlines: The Hits of a-ha', 'Die Meistersinger von Nürnberg']}, 'ar_combined_artist': {'category': 'common', 'data_type': 'str', 'description': 'The first non-empty value of the following list of fields: “albumartist” -> “artist” -> “albumartist_credit” -> “artist_credit” -> “albumartist_sort” -> “artist_sort”. If no value could be determined, then “Unknown” is assigned. The second artist after “feat.”, “ft.” or “vs.” is removed.', 'examples': ['a-ha', 'Richard Wagner; René Kollo, Helen Donath, ...']}, 'ar_combined_artist_sort': {'category': 'common', 'data_type': 'str', 'description': 'The first non-empty value of the following list of fields: “albumartist_sort” -> “artist_sort” -> “albumartist” -> “artist” -> “albumartist_credit” -> “artist_credit”. If no value could be determined, then “Unknown” is assigned. The second artist after “feat.”, “ft.” or “vs.” is removed.', 'examples': ['a-ha', 'Wagner, Richard; Kollo, René, Donath, Helen...']}, 'ar_combined_composer': {'category': 'common', 'data_type': 'str', 'description': 'The first not empty field of this field list: “composer_sort”, “composer”, “ar_combined_artist”', 'examples': ['Beethoven, Ludwig-van', 'Wagner, Richard']}, 'ar_combined_disctrack': {'category': 'common', 'data_type': 'str', 'description': 'Combination of disc and track in the format: disk-track', 'examples': ['1-01', '3-099']}, 'ar_combined_soundtrack': {'category': 'common', 'data_type': 'bool', 'description': 'Boolean flag which indicates if the audio file is a soundtrack', 'examples': [True, False]}, 'ar_combined_work_top': {'category': 'common', 'data_type': 'str', 'description': 'The work on the top level of a work hierarchy.', 'examples': ['Horn Concerto: I. Allegro', 'Die Meistersinger von Nürnberg']}, 'ar_combined_year': {'category': 'common', 'data_type': 'int', 'description': 'First “original_year” then “year”.', 'examples': [1978]}, 'ar_initial_album': {'category': 'common', 'description': 'First character in lowercase of “ar_combined_album”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Help!” -> “h”.', 'examples': ['h']}, 'ar_initial_artist': {'category': 'common', 'data_type': 'str', 'description': 'First character in lowercase of “ar_combined_artist_sort”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Brendel, Alfred” -> “b”.', 'examples': ['b']}, 'ar_initial_composer': {'category': 'common', 'data_type': 'str', 'description': 'First character in lowercase of “ar_combined_composer”. Allowed characters: [a-z, 0, _], 0-9 -> 0, ? -> _. For example “Ludwig van Beethoven” -> “l”.', 'examples': ['l']}, 'ar_performer': {'category': 'common', 'data_type': 'str', 'description': 'Performer names.', 'examples': ['Herbert von Karajan, Staatskapelle Dresden']}, 'ar_performer_raw': {'category': 'common', 'data_type': 'list', 'description': 'Raw performer names.', 'examples': [[['conductor', 'Herbert von Karajan'], ['orchestra', 'Staatskapelle Dresden']]]}, 'ar_performer_short': {'category': 'common', 'data_type': 'str', 'description': 'Abbreviated performer names.', 'examples': ['Karajan, StaDre']}}¶: Documentation of the extra fields.

audiorename.args.parse_args(argv: Optional[Tuple[str]]) → ArgsDefault[source]¶

Parse the command line arguments using the python library argparse.

Parameters: argv (list) – The command line arguments specified as a list: e. g ['--dry-run', '.']
Returns: Dictionary see audiorename.args.ArgsDefault

audiorename.audiofile module¶

This module contains all functionality on the level of a single audio file.

class audiorename.audiofile.Action(job: Job)[source]¶

Bases: object

Parameters: job (audiorename.job.Job) – The job object.

class audiorename.audiofile.AudioFile(path: str, job: Job, file_type: Literal['source', 'target'] = 'source', prefix: Optional[str] = None)[source]¶

Bases: object

Parameters

path – The path string of the audio file.
job – The current job object.
file_type (string) – Either “source” or “target”.
prefix (string) – The path prefix of the audio file, for example the base folder of your music collection. Used to shorten the path strings in the progress messaging.

property abspath: str¶: The absolute path of the audio file.

property dir_and_file: str¶: The parent directory name and the file name.

property extension: str¶: The file extension of the audio file.

property filename: str¶: The file name of the audio file.

audiorename.audiofile.detect_best_format(source: Meta, target: Meta, job: Job) → Literal['source', 'target'][source]¶

Parameters

source – The metadata object of the source file.
target – The metadata object of the target file.
job – The job object.

Returns

Either the string source or the string target

audiorename.audiofile.find_target_path(target: str, extensions: List[str]) → Optional[str][source]¶: Get the path of a existing audio file target. Search for audio files with different extensions.

audiorename.audiofile.process_target_path(meta: Meta, format_string: str, shell_friendly: bool = True)[source]¶

Parameters

meta (dict) – The to a dictionary converted attributes of a meta object audiorename.meta.Meta.
format_string (string) –
shell_friendly (boolean) –

audiorename.batch module¶

Batch processing of the audio files.

class audiorename.batch.Batch(job: Job)[source]¶

Bases: object

This class first sorts all files and then walks through all files. In this process it tries to make bundles of files belonging to an album. This bundle of files is temporary stored in the attribute virtual_album. This complicated mechanism is needed for the two filters album_complete and album_min.

check_completeness()[source]¶: Check if the album is complete

check_extension(path: str) → bool[source]¶

Check the extension of the track.

Params str path: The path of the tracks.

check_quantity()[source]¶: Compare the number of tracks in an album with the minimal track threshold.

current_album_title: str = ''¶: Storage for the album title of the current audio file.

execute()[source]¶: Process all files of a given path or process a single file.

make_bundles(path: str = '')[source]¶

Params str path: The path of the tracks.

process_album()[source]¶: Check an album for quantity and completeness.

virtual_album: List[VirtualAlbum] = []¶: Storage of a list of files belonging to an album.

audiorename.job module¶

Collect all informations about the current job in a class.

class audiorename.job.CliOutputConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶: Bases: Config

class audiorename.job.Config(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶

Bases: object

The class Config is used to combine the two sources of settings (command line arguments and INI configuration file). The command line arguments override the values of the configuration file. This class is to be inherited by subclasses. Each subclass corresponds to a section of the INI configuration file. All settings are saved as private properties with leading underscore. The subclass provide for each private property a getter method (@property)

class audiorename.job.FiltersConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶: Bases: Config

class audiorename.job.Job(args: ArgsDefault)[source]¶

Bases: object

Holds informations of one job which can handle multiple files.

A jobs represents one call of the program on the command line. This class unifies and processes the data of the argparse and the configparser call. It groups the argparse and the configparser key-value pairs into parent properties. The properties of this class for example can be used to display easily an overview message of the job.

class audiorename.job.MetadataActionsConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶: Bases: Config

class audiorename.job.PathTemplatesConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶

Bases: Config

A class to store the selected or configured path templates. This class can be accessed under the attibute path_templates of the Job class.

property classical: str¶: Get the path template for classical music.

property compilation: str¶: Get the path template for compilations.

property default: str¶: Get the default path template.

property soundtrack: str¶: Get the path template for soundtracks.

class audiorename.job.RenameConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶: Bases: Config

class audiorename.job.SelectionConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶

Bases: Config

property source: str¶: The source path as an absolute path. It maybe a directory or a file.

property target: Optional[str]¶: The path of the target as an absolute path. It is always a directory.

class audiorename.job.TemplateSettingsConfig(job: Job, section: str, options: Dict[str, Literal['boolean', 'integer', 'string']])[source]¶: Bases: Config

audiorename.message module¶

Print messages on the command line.

class audiorename.message.Message(job: Job)[source]¶

Bases: object

Print messages on the command line interface.

Parameters: job (audiorename.job.Job) – The job object.

audiorename.meta module¶

Extend the class MediaFile of the package phrydy.

class audiorename.meta.Meta(path: str, shell_friendly: bool = False)[source]¶

Bases: MediaFileExtended

__init__(path: str, shell_friendly: bool = False)[source]¶

Constructs a new MediaFile reflecting the provided file.

filething can be a path to a file (i.e., a string) or a file-like object.

May throw UnreadableFileError.

By default, MP3 files are saved with ID3v2.4 tags. You can use the older ID3v2.3 standard by specifying the id3v23 option.

property ar_classical_album: Optional[str]¶

Uses:

phrydy.mediafile.MediaFile.work

Examples:

Horn Concerto: I. Allegro → Horn Concerto
Die Meistersinger von Nürnberg

property ar_classical_performer: str¶

http://musicbrainz.org/doc/Style/Classical/Release/Artist

Uses:

audiorename.meta.Meta.ar_performer_short
phrydy.mediafile.MediaFile.albumartist

property ar_classical_title: Optional[str]¶

Uses:

phrydy.mediafile.MediaFile.title

Example:

Horn Concerto: I. Allegro

property ar_classical_track: Optional[str]¶

Uses:

audiorename.meta.Meta.ar_classical_title
audiorename.meta.Meta.ar_combined_disctrack

property ar_combined_album: Optional[str]¶

Uses:

phrydy.mediafile.MediaFile.album

Example:

Just Friends (Disc 2) → Just Friends

property ar_combined_artist: str¶

Uses:

phrydy.mediafile.MediaFile.albumartist
phrydy.mediafile.MediaFile.artist
phrydy.mediafile.MediaFile.albumartist_credit
phrydy.mediafile.MediaFile.artist_credit
phrydy.mediafile.MediaFile.albumartist_sort
phrydy.mediafile.MediaFile.artist_sort

Removes the second artist after feat., ft. or vs..

property ar_combined_artist_sort: str¶

Uses:

phrydy.mediafile.MediaFile.albumartist_sort
phrydy.mediafile.MediaFile.artist_sort
phrydy.mediafile.MediaFile.albumartist
phrydy.mediafile.MediaFile.artist
phrydy.mediafile.MediaFile.albumartist_credit
phrydy.mediafile.MediaFile.artist_credit

Removes the second artist after feat., ft. or vs..

property ar_combined_composer: str¶

Uses:

phrydy.mediafile.MediaFile.composer_sort
phrydy.mediafile.MediaFile.composer
audiorename.meta.Meta.ar_combined_artist

property ar_combined_disctrack: Optional[str]¶

Generate a combination of track and disc number, e. g.: 1-04, 3-06.

Uses:

phrydy.mediafile.MediaFile.disctotal
phrydy.mediafile.MediaFile.disc
phrydy.mediafile.MediaFile.tracktotal
phrydy.mediafile.MediaFile.track

property ar_combined_work_top: Optional[str]¶

Uses:

phrydy.mediafile.MediaFile.work_hierarchy
phrydy.mediafile.MediaFile.work

property ar_combined_year¶

Uses:

phrydy.mediafile.MediaFile.original_year
phrydy.mediafile.MediaFile.year

property ar_initial_album: Optional[str]¶

Uses:

audiorename.meta.Meta.ar_combined_album

Examples:

Just Friends → j
Die Meistersinger von Nürnberg → d

property ar_initial_artist: str¶

Uses:

audiorename.meta.Meta.ar_combined_artist_sort

Examples:

Just Friends → j
Die Meistersinger von Nürnberg → d

property ar_initial_composer: str¶

Uses:

audiorename.meta.Meta.ar_combined_composer

property ar_performer: str¶

Uses:

audiorename.meta.Meta.ar_performer_raw

property ar_performer_raw: List[List[str]]¶

Generate a unifed ar_performer list.

Picard doesn’t store ar_performer values in m4a, alac.m4a, wma, wav, aiff.

Returns: A list

[
    ['conductor', 'Herbert von Karajan'],
    ['violin', 'Anne-Sophie Mutter'],
]

Uses:

phrydy.mediafile.MediaFile.mgfile

property ar_performer_short¶

Uses:

phrydy.mediafile.MediaFile.ar_performer_raw

export_dict(sanitize: bool = True) → Dict[str, str][source]¶

Export all fields into a dictionary.

Parameters: sanitize – Set the parameter to true to trigger the sanitize function.

classmethod fields()[source]¶: Get the names of all writable properties that reflect metadata tags (i.e., those that are instances of MediaField).

remap_classical() → None[source]¶: Remap some fields to fit better for classical music: composer becomes artist, work becomes album, from the title the work prefix is removed (Symphonie No. 9: I. Allegro -> I. Allegro) and track becomes the movement number. All overwritten fields are safed in the comments field. No combined properties (like ar_combined_composer) are used and therefore some code duplications are done on purpose to avoid circular endless loops.

audiorename.meta.compare_dicts(first: Dict[str, str], second: Dict[str, str]) → List[Tuple[str, Optional[str], Optional[str]]][source]¶

Compare two dictionaries for differenes.

Parameters

first – First dictionary to diff.
second – Second dicationary to diff.

Returns

As list of key entries whose values differ.

audiorename.musicbrainz module¶

class audiorename.musicbrainz.Artist¶: Bases: dict

class audiorename.musicbrainz.ArtistRelation¶: Bases: dict

class audiorename.musicbrainz.Work¶

Bases: dict

get_work_by_id with work-rels

{
  "work": {
    "work-relation-list": [
      {
        "type-id": "ca8d3642-ce5f-49f8-91f2-125d72524e6a",
        "direction": "backward",
        "target": "5adc213f-700a-4435-9e95-831ed720f348",
        "ordering-key": "3",
        "work": {
          "id": "5adc213f-700a-4435-9e95-831ed720f348",
          "language": "deu",
          "title": "Die Zauberflöte, K. 620: Akt I"
        },
        "type": "parts"
      },
      {
        "type-id": "51975ed8-bbfa-486b-9f28-5947f4370299",
        "work": {
          "disambiguation": "for piano, arr. Matthias",
          "id": "798f4c25-0ab3-44ba-81b6-3d856aedf82a",
          "language": "zxx",
          "title": "Die Zauberflöte, K. 620: Aria ..."
        },
        "type": "arrangement",
        "target": "798f4c25-0ab3-44ba-81b6-3d856aedf82a"
      }
    ],
    "type": "Aria",
    "id": "eafec51f-47c5-3c66-8c36-a524246c85f8",
    "language": "deu",
    "title": "Die Zauberflöte: Act I, Scene II. No. 2 Aria ..",
    "artist-relation-list": [
      {
        "type-id": "7474ab81-486f-40b5-8685-3a4f8ea624cb",
        "direction": "backward",
        "type": "librettist",
        "target": "86104c7c-cda4-4798-a4ab-104318c7ae9c",
        "artist": {
          "sort-name": "Schikaneder, Emanuel",
          "id": "86104c7c-cda4-4798-a4ab-104318c7ae9c",
          "name": "Emanuel Schikaneder"
        }
      },
      {
        "begin": "1791",
        "end": "1791",
        "target": "b972f589-fb0e-474e-b64a-803b0364fa75",
        "artist": {
          "sort-name": "Mozart, Wolfgang Amadeus",
          "disambiguation": "classical composer",
          "id": "b972f589-fb0e-474e-b64a-803b0364fa75",
          "name": "Wolfgang Amadeus Mozart"
        },
        "direction": "backward",
        "type-id": "d59d99ea-23d4-4a80-b066-edca32ee158f",
        "ended": "true",
        "type": "composer"
      }
    ]
  }
}

{
  "work": {
    "work-relation-list": [
      {
        "type-id": "c1dca2cd-194c-36dd-93f8-6a359167e992",
        "direction": "backward",
        "work": {
          "id": "70e53569-258c-463d-9505-5b69dcbf374a",
          "title": "Can’t Stop the Classics, Part 2"
        },
        "type": "medley",
        "target": "70e53569-258c-463d-9505-5b69dcbf374a"
      },
      {
        "type-id": "ca8d3642-ce5f-49f8-91f2-125d72524e6a",
        "direction": "backward",
        "target": "73663bd3-392f-45a7-b4ff-e75c01f5926a",
        "ordering-key": "1",
        "work": {
          "id": "73663bd3-392f-45a7-b4ff-e75c01f5926a",
          "language": "deu",
          "title": "Die Meistersinger von Nürnberg, WWV 96: Akt I"
        },
        "type": "parts"
      }
    ]
  }
}

audiorename.musicbrainz.WorkChild¶: alias of Work

class audiorename.musicbrainz.WorkRelation¶: Bases: dict