mmusicc.formats package¶

Important

Make sure to call formats.init() before using the modules automatic loading functions/classes!

Module contents¶

mmusicc.formats.init()[source]¶

Initialize the formats module, loading all formats for loader.

Before this is called loading a file and unpickling will not work. If the module was already initialized, the initialisation is skipped.

mmusicc.formats.MusicFile(file_path)[source]¶

Returns a AudioFile instance or None if file type is not supported

Note

Make sure that allocationmap is initialized before loading any files.

Parameters:	file_path (pathlib.Path) – path of file to load as MusicFile
Returns:	audio file instance of file in specified path
Return type:	AudioFile

exception mmusicc.formats.AudioFileError[source]¶: Base error for AudioFile, mostly IO/parsing related operations

Hint

the following attributes are imported in __init__. I don’t know how to document them with their docstring as I did with init and MusicFile.

mmusicc.formats._misc.mimes¶

A set of supported mime types. Empty until init.

Type:	set

mmusicc.formats._misc.types¶

A set of AudioFile subclasses. Empty until init.

Type:	set

mmusicc.formats._misc.loaders¶

A dict mapping file extensions to loaders (function returning an AudioFile object). Empty until init.

Type:	dict

mmusicc.formats._audio module¶

class mmusicc.formats._audio.AudioFile[source]¶

Bases: object

Base class for all audio files wrapping tags and audio stream info.

_file¶

file path of file.

Type:	pathlib.Path

_dict_meta¶

metadata from file (the parsed one)

Type:	MetadataDict

unprocessed_tag¶

metadata that could’nt be associated. Manly used to manually update the association list with new tags/tag names.

Type:	dict

file_path¶

file path of audio file.

Type:	pathlib.Path

dict_meta¶

metadata of the audio file (the parsed one).

Type:	MetadataDict

file_read()[source]¶: reads file tags into AudioFile tag dictionary (dict_meta).

file_save(remove_existing=False, write_empty=False, dry_run=False)[source]¶

saves file tags from tag dictionary (dict_meta) to AudioFile.

Parameters:	remove_existing (bool) – if true clear all tags before writing. Defaults to False. write_empty (bool) – if true write tags with Empty Value, if false, the tag will not be created and a existing tag will be deleted. Behaviour might slightly differ between tag types. Defaults to False. dry_run (bool) – if true, do anything but saving to file. Defaults to False
Returns:	1 if data was saved to file, zero if nothing was changed on file.
Return type:	int

mmusicc.formats.mp3 module¶

mmusicc.formats.mp3.extensions = ['.mp3', '.mp2', '.mp1', '.mpg', '.mpeg']¶: list of all extensions associated with this module

class mmusicc.formats.mp3.MP3File(file_path)[source]¶

Bases: mmusicc.formats._audio.AudioFile

Tag object for mp3 files using ID3 tag standard.

Instance created by loader (at the bottom of this code) which in this case is this class itself (vgl. xiph).

Parameters:	file_path (str) – file path of represented audio file

format = 'MP3'¶

mimes = ['audio/mp3', 'audio/x-mp3', 'audio/mpeg', 'audio/mpg', 'audio/x-mpeg']¶

file_read()[source]¶

reads file tags into AudioFile tag dictionary (dict_meta).

First tries to associate ID3 tags, than takes all txxx tags and runs them through the scan dictionary function.

file_save(remove_existing=False, write_empty=False, remove_v1=False, dry_run=False)[source]¶

saves file tags from tag dictionary (dict_meta) to AudioFile.

Note

write_empty may have no effect. Since mutagen will not load empty tags it can’t be checked. Correction or Info is appreciated.

Parameters:	remove_existing ('bool', optional) – if true clear all tags on file before writing. Defaults to False. write_empty (bool) – Only affects TXXX tags. Existing tags will always be set to None. If true create empty TXXX tags with value none. If false no tag will be created or existing TXXX tag on file will be deleted. Defaults to False. remove_v1 ('bool') – If True, remove existing ID3.V1 tags. Defaults to False. dry_run (bool) – if true, do anything but saving to file. Defaults to False
Returns:	1 if data was saved to file, zero if nothing was changed on file.
Return type:	int

mmusicc.formats.mp3.types = [<class 'mmusicc.formats.mp3.MP3File'>]¶: list of all subclasses of AudioFile in this module

mmusicc.formats.mp3.loader¶

class alias for dynamic loading of available AudioFile subclasses

alias of mmusicc.formats.mp3.MP3File

mmusicc.formats.xiph module¶

mmusicc.formats.xiph.extensions = ['.ogg', '.oga', '.flac', '.opus']¶: list of all extensions associated with this module

class mmusicc.formats.xiph.VCFile(audio)[source]¶

Bases: mmusicc.formats._audio.AudioFile

Tag object for all files using tags of the xiph v-comment tag standard.

Instance created by loader (at the bottom of this code).

Parameters:	audio (mutagen.File) – file as mutagen file object.

format = 'Unknown Mutagen + vorbiscomment'¶

MutagenType = None¶

can_change_images = True¶

file_read()[source]¶: reads file tags into AudioFile tag dictionary (dict_meta).

file_save(remove_existing=False, write_empty=False, dry_run=False)[source]¶

saves file tags from tag dictionary (dict_meta) to AudioFile.

if no value changes the file is not saved, therefore there will be no changes at file (mtime does not change). When remove_existing is set, the file is saved, when unprocessed tags exists.

Parameters:	remove_existing (bool) – if true clear all tags on file before writing. Defaults to False. write_empty (bool) – if true write empty tags an therefore create a tag with content “”. If false no tag will be created and existing tags on file that would be overwritten with “” will be deleted. Defaults to False. dry_run (bool) – if true, do anything but saving to file. Defaults to False
Returns:	1 if data was saved to file, zero if nothing was changed on file.
Return type:	int

Note

A tag not existing in dict_meta or being None in dict_meta will not be deleted and es kept unchanged. The (possible empty) tag will be deleted, when an Empty value is in source and write_empty is False.

class mmusicc.formats.xiph.OggFile(audio)[source]¶

Bases: mmusicc.formats.xiph.VCFile

File type specific subclass of VCFile

format = 'Ogg Vorbis'¶

mimes = ['audio/vorbis', 'audio/x-vorbis', 'audio/ogg', 'audio/x-ogg']¶

MutagenType¶: alias of mutagen.oggvorbis.OggVorbis

class mmusicc.formats.xiph.OggOpusFile(audio)[source]¶

Bases: mmusicc.formats.xiph.VCFile

format = 'Ogg Opus'¶

mimes = ['audio/opus', 'audio/x-opus', 'audio/ogg', 'audio/ogg; codecs=opus']¶

MutagenType¶: alias of mutagen.oggopus.OggOpus

class mmusicc.formats.xiph.FLACFile(audio)[source]¶

Bases: mmusicc.formats.xiph.VCFile

File type specific subclass of VCFile

format = 'FLAC'¶

mimes = ['audio/flac', 'audio/x-flac']¶

MutagenType¶: alias of mutagen.flac.FLAC

mmusicc.formats.xiph.types = [<class 'mmusicc.formats.xiph.OggFile'>, <class 'mmusicc.formats.xiph.OggOpusFile'>, <class 'mmusicc.formats.xiph.FLACFile'>]¶: list of all subclasses of AudioFile in this module

mmusicc.formats.xiph.loader(file_path)[source]¶

loads the given file into a VCFile object and returns it.

Parameters:	file_path (str) – path of file to be loaded.
Returns:	VCFile tag objects with given file loaded.
Return type:	AudioFile
Raises:	`AudioFileError` – if file type could not be determined.