audiorename package

Module contents

Rename audio files from metadata tags.

audiorename.execute(*argv)[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[source]

Bases: object

This is a dummy class. The code only exists to document the return value of the audiorename.args.parse_args(). It can also be used to mock the args object for testing purposes.

album_complete = False
album_min = False
backup = False
backup_folder = False
best_format = False
classical = False
color = False
compilation = False
copy = False
debug = False
delete = False
dry_run = False
enrich_metadata = False
extension = 'mp3,m4a,flac,wma'
field_skip = False
format = False
format_classical = False
genre_classical = ','
job_info = False
mb_track_listing = False
move = False
no_color = False
no_rename = False
one_line = False
remap_classical = False
shell_friendly = False
soundtrack = False
source = '.'
source_as_target = False
stats = False
target = ''
verbose = False
audiorename.args.description()[source]

Build the description string.

audiorename.args.fields = {'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 available value of this metatag order: “albumartist” -> “artist” -> “albumartist_credit” -> “artist_credit”', 'examples': ['a-ha', 'Richard Wagner; René Kollo, Helen Donath, ...']}, 'ar_combined_artist_sort': {'category': 'common', 'data_type': 'str', 'description': 'The first available value of this metatag order: “albumartist_sort” -> “artist_sort” -> “ar_combined_artist”', '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”.', 'examples': ['h']}, 'ar_initial_artist': {'category': 'common', 'data_type': 'str', 'description': 'First character in lowercase of “ar_combined_artist_sort”', 'examples': ['b']}, 'ar_initial_composer': {'category': 'common', 'data_type': 'str', 'description': 'First character in lowercase of “ar_combined_composer”. 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)[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.batch module

Batch processing of the audio files.

class audiorename.batch.Batch(job: audiorename.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 = ''

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='')[source]
Params str path:
 The path of the tracks.
process_album()[source]

Check an album for quantity and completeness.

virtual_album = []

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.Counter[source]

Bases: object

count(counter: str)[source]

Add one to number identified by a string.

Parameters:counter – A string to identify the counter
Returns:None
get(counter: str) → int[source]

Get the counter identify by a string.

Parameters:counter (str) – A string to identify the counter
Returns:The counter as a number
Return type:int
reset()[source]
result() → str[source]
class audiorename.job.DefaultFormats[source]

Bases: object

classical = '$ar_initial_composer/$ar_combined_composer/%shorten{$ar_combined_work_top,48}_[%shorten{$ar_classical_performer,32}]/${ar_combined_disctrack}_%shorten{$ar_classical_title,64}%ifdefnotempty{acoustid_id,_%shorten{$acoustid_id,8}}'
compilation = '_compilations/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}'
default = '$ar_initial_artist/%shorten{$ar_combined_artist_sort}/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_%shorten{$title}'
soundtrack = '_soundtrack/$ar_initial_album/%shorten{$ar_combined_album}%ifdefnotempty{ar_combined_year,_${ar_combined_year}}/${ar_combined_disctrack}_${artist}_%shorten{$title}'
class audiorename.job.Formats(args)[source]

Bases: object

classical = ''
compilation = ''
default = ''
soundtrack = ''
class audiorename.job.Job(args)[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 call. It groups the argparse 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.

filter
format

default compilation soundtrack

metadata_actions
output
source

The source path as an absolute path. It maybe a directory or a file.

stats = <audiorename.job.Stats object>
target

The path of the target as an absolute path. It is always a directory.

class audiorename.job.RenameAction(args)[source]

Bases: object

backup_folder
cleanup
move
Returns:
Return type:string
  • copy
  • move
  • no_rename
class audiorename.job.Stats[source]

Bases: object

counter = <audiorename.job.Counter object>
timer = <audiorename.job.Timer object>
class audiorename.job.Timer[source]

Bases: object

begin = 0
end = 0
result()[source]
start()[source]
stop()[source]

audiorename.message module

Print messages on the command line.

class audiorename.message.KeyValue(color: bool = False)[source]

Bases: object

add(key, value) → None[source]
result() → str[source]
result_one_line() → str[source]
class audiorename.message.Message(job)[source]

Bases: object

Print messages on the command line interface.

Parameters:job (audiorename.job.Job) – The job object.
action_one_path(message: str, audio_file: AudioFile) → None[source]
action_two_path(message: str, source: AudioFile, target: AudioFile) → None[source]
best_format(best, attr, source: Meta, target: Meta) → None[source]
diff(key, value1, value2)[source]
static max_fields_length() → int[source]
next_file(audio_file: AudioFile)[source]
output(text='') → None[source]
status(text: str, status: Literal[ok, error, progress])[source]
status_color(status: Literal[ok, error, progress]) → Literal[yellow, red, green][source]
template_indent(level: int = 1) → str[source]
template_path(audio_file: AudioFile)[source]
audiorename.message.job_info(job: Job) → None[source]
audiorename.message.stats(job: Job) → None[source]

audiorename.meta module

Extend the class MediaFile of the package phrydy.

import json
print(json.dumps(result,indent=2))

get_recording_by_id with work-rels

soundtrack/Pulp-Fiction/01.mp3

{
  "recording": {
    "length": "149000",
    "id": "0480672d-4d88-4824-a06b-917ff408eabe",
    "title": "Pumpkin and Honey Bunny ..."
  }
}

classical/Mozart_Horn-concertos/01.mp3

{
  "recording": {
    "length": "286826",
    "work-relation-list": [
      {
        "type-id": "a3005666-a872-32c3-ad06-98af558e99b0",
        "begin": "1987-03",
        "end": "1987-03",
        "target": "21fe0bf0-a040-387c-a39d-369d53c251fe",
        "ended": "true",
        "work": {
          "id": "21fe0bf0-a040-387c-a39d-369d53c251fe",
          "language": "zxx",
          "title": "Concerto [...] KV 412: I. Allegro"
        },
        "type": "performance"
      }
    ],
    "id": "7886ad6c-11af-435b-8ec3-bca5711f7728",
    "title": "Konzert für [...] K. 386b/514: I. Allegro"
  }
}

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"
      }
    ]
  }
}

get_release_by_id with release-groups

soundtrack/Pulp-Fiction/01.mp3

{
  "release": {
    "status": "Bootleg",
    "release-event-count": 1,
    "title": "Pulp Fiction",
    "country": "US",
    "cover-art-archive": {
      "count": "1",
      "front": "true",
      "back": "false",
      "artwork": "true"
    },
    "release-event-list": [
      {
        "date": "2005-12-01",
        "area": {
          "sort-name": "United States",
          "iso-3166-1-code-list": [
            "US"
          ],
          "id": "489ce91b-6658-3307-9877-795b68554c98",
          "name": "United States"
        }
      }
    ],
    "release-group": {
      "first-release-date": "1994-09-27",
      "secondary-type-list": [
        "Compilation",
        "Soundtrack"
      ],
      "primary-type": "Album",
      "title": "Pulp Fiction: Music From the Motion Picture",
      "type": "Soundtrack",
      "id": "1703cd63-9401-33c0-87c6-50c4ba2e0ba8"
    },
    "text-representation": {
      "language": "eng",
      "script": "Latn"
    },
    "date": "2005-12-01",
    "quality": "normal",
    "id": "ab81edcb-9525-47cd-8247-db4fa969f525",
    "asin": "B000002OTL"
  }
}

classical/Mozart_Horn-concertos/01.mp3

{
  "release": {
    "status": "Official",
    "release-event-count": 1,
    "title": "4 Hornkonzerte (Concertos for Horn and Orchestra)",
    "country": "DE",
    "barcode": "028942781429",
    "cover-art-archive": {
      "count": "0",
      "front": "false",
      "back": "false",
      "artwork": "false"
    },
    "release-event-list": [
      {
        "date": "1988",
        "area": {
          "sort-name": "Germany",
          "iso-3166-1-code-list": [
            "DE"
          ],
          "id": "85752fda-13c4-31a3-bee5-0e5cb1f51dad",
          "name": "Germany"
        }
      }
    ],
    "release-group": {
      "first-release-date": "1988",
      "title": "4 Hornkonzerte (Concertos for Horn and Orchestra)",
      "type": "Album",
      "id": "e1fa28f0-e56e-395b-82d3-a8de54e8c627",
      "primary-type": "Album"
    },
    "text-representation": {
      "language": "deu",
      "script": "Latn"
    },
    "date": "1988",
    "quality": "normal",
    "id": "5ed650c5-0f72-4b79-80a7-c458c869f53e",
    "asin": "B00000E4FA"
  }
}
class audiorename.meta.Meta(path, shell_friendly: bool = False)[source]

Bases: phrydy.mediafile_extended.MediaFileExtended

__init__(path, 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.

__module__ = 'audiorename.meta'
static _initials(value: str) → str[source]
Parameters:value (str) – A string to extract the initials.
static _normalize_performer(ar_performer: List[str]) → List[List[str]][source]
Parameters:ar_performer (list) – A list of raw ar_performer strings like 
['John Lennon (vocals)', 'Ringo Starr (drums)']
Returns:A list 
[
    ['vocals', 'John Lennon'],
    ['drums', 'Ringo Starr'],
]
static _roman_to_int(n: str) → int[source]
static _sanitize(value) → str[source]
static _shorten_performer(ar_performer: str, length: int = 3, separator: str = ' ', abbreviation: str = '.') → str[source]
static _unify_list(seq)[source]

https://www.peterbe.com/plog/uniqifiers-benchmark

ar_classical_album

Uses:

  • phrydy.mediafile.MediaFile.work

Examples:

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

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

Uses:

ar_classical_title

Uses:

  • phrydy.mediafile.MediaFile.title

Example:

  • Horn Concerto: I. Allegro
ar_classical_track

Uses:

ar_combined_album

Uses:

  • phrydy.mediafile.MediaFile.album

Example:

  • Just Friends (Disc 2) → Just Friends
ar_combined_artist

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
ar_combined_artist_sort

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
ar_combined_composer

Uses:

ar_combined_disctrack

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
ar_combined_soundtrack
ar_combined_work_top

Uses:

  • phrydy.mediafile.MediaFile.work_hierarchy
  • phrydy.mediafile.MediaFile.work
ar_combined_year

Uses:

  • phrydy.mediafile.MediaFile.original_year
  • phrydy.mediafile.MediaFile.year
ar_initial_album

Uses:

Examples:

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

Uses:

Examples:

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

Uses:

ar_performer

Uses:

ar_performer_raw

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
ar_performer_short

Uses:

  • phrydy.mediafile.MediaFile.ar_performer_raw
enrich_metadata() → None[source]
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).

classmethod fields_audiorename()[source]
classmethod fields_phrydy()[source]
classmethod fields_sorted()[source]
remap_classical() → None[source]

Remap some fields to fit better for classical music. For example composer becomes artist and work becomes album. 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[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.meta.query_mbrainz(mb_type: Literal[recording, work, release], mb_id: str) → Optional[Dict[str, Any]][source]
audiorename.meta.query_works_recursively(work_id: str, works=[])[source]
audiorename.meta.set_useragent() → None[source]

audiorename.audiofile module

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

class audiorename.audiofile.Action(job)[source]

Bases: object

Parameters:job (audiorename.job.Job) – The job object.
backup(audio_file)[source]
cleanup(audio_file)[source]
copy(source, target)[source]
count(counter_name)[source]
create_dir(audio_file)[source]
delete(audio_file)[source]
metadata(audio_file: audiorename.audiofile.AudioFile, enrich: bool = False, remap: bool = False) → None[source]
move(source, target)[source]
class audiorename.audiofile.AudioFile(path: str, job: audiorename.job.Job, file_type: Literal[source, target] = 'source', prefix=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.
abspath

The absolute path of the audio file.

dir_and_file

The parent directory name and the file name.

exists
extension

The file extension of the audio file.

filename

The file name of the audio file.

meta
prefix
shell_friendly
short
class audiorename.audiofile.MBTrackListing[source]

Bases: object

format_audiofile(album, title, length)[source]
audiorename.audiofile.detect_best_format(source: audiorename.meta.Meta, target: audiorename.meta.Meta, job: audiorename.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.do_job_on_audiofile(source_path: str, job: audiorename.job.Job)[source]
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, format_string, shell_friendly=True)[source]
Parameters:
  • meta (dict) – The to a dictionary converted attributes of a meta object audiorename.meta.Meta.
  • format_string (string) –
  • shell_friendly (boolean) –