audiorename package

Module contents

Rename audio files from metadata tags.

audiorename.execute(*argv: str) → None[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: Tuple[str] | None) → 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: str | None = 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]) → str | None[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: str | None

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: str | None

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:

property ar_classical_title: str | None

Uses:

  • phrydy.mediafile.MediaFile.title

Example:

  • Horn Concerto: I. Allegro

property ar_classical_track: str | None

Uses:

property ar_combined_album: str | None

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:

property ar_combined_disctrack: str | None

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: str | None

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: str | None

Uses:

Examples:

  • Just Friends → j

  • Die Meistersinger von Nürnberg → d

property ar_initial_artist: str

Uses:

Examples:

  • Just Friends → j

  • Die Meistersinger von Nürnberg → d

property ar_initial_composer: str

Uses:

property ar_performer: str

Uses:

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, str | None, str | None]][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